fix: survive fast refresh without disposing native objects

Introduce useDisposableMemo — a useMemo replacement for native-backed
objects that need deterministic cleanup. Disposal happens in the render
phase on deps change, and on unmount via deferred setTimeout(0) in dev
(cancelled if fast refresh re-mounts) or synchronously in production.

Migrates useRiveProperty, useRiveList, and useViewModelInstance to use
it, fixing the "NativeState is null" crash on HMR.

Author: mfazekas

src/hooks/useDisposableMemo.ts

@@ -0,0 +1,75 @@
+import { useRef, useEffect, type DependencyList } from 'react';
+
+const UNINITIALIZED = Symbol('UNINITIALIZED');
+
+function depsEqual(a: DependencyList, b: DependencyList): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!Object.is(a[i], b[i])) return false;
+  }
+  return true;
+}
+
+/**
+ * Like `useMemo`, but with a cleanup callback for disposable native resources.
+ *
+ * - Value is created synchronously during render (available on first render).
+ * - When deps change, the old value is cleaned up during render and a new one
+ *   is created.
+ * - On unmount in production: cleaned up synchronously in effect cleanup.
+ * - On unmount in development: cleanup is deferred via `setTimeout(0)` so that
+ *   fast refresh and Strict Mode can cancel it when effects re-run.
+ */
+export function useDisposableMemo<T>(
+  factory: () => T,
+  cleanup: (value: T) => void,
+  deps: DependencyList
+): T {
+  const ref = useRef<{
+    value: T;
+    deps: DependencyList | typeof UNINITIALIZED;
+    pendingDisposal: ReturnType<typeof setTimeout> | null;
+  }>({
+    value: undefined as T,
+    deps: UNINITIALIZED,
+    pendingDisposal: null,
+  });
+  const cleanupRef = useRef(cleanup);
+  cleanupRef.current = cleanup;
+
+  if (
+    ref.current.deps === UNINITIALIZED ||
+    !depsEqual(ref.current.deps, deps)
+  ) {
+    if (__DEV__ && ref.current.pendingDisposal !== null) {
+      clearTimeout(ref.current.pendingDisposal);
+      ref.current.pendingDisposal = null;
+    }
+    if (ref.current.deps !== UNINITIALIZED) {
+      cleanupRef.current(ref.current.value);
+    }
+    ref.current = { value: factory(), deps, pendingDisposal: null };
+  }
+
+  useEffect(() => {
+    if (__DEV__) {
+      if (ref.current.pendingDisposal !== null) {
+        clearTimeout(ref.current.pendingDisposal);
+        ref.current.pendingDisposal = null;
+      }
+    }
+    return () => {
+      if (__DEV__) {
+        const val = ref.current.value;
+        ref.current.pendingDisposal = setTimeout(() => {
+          cleanupRef.current(val);
+          ref.current.pendingDisposal = null;
+        }, 0);
+      } else {
+        cleanupRef.current(ref.current.value);
+      }
+    };
+  }, []);
+
+  return ref.current.value;
+}

src/hooks/useRiveList.ts

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useState, useMemo } from 'react';
 import type { ViewModelInstance } from '../specs/ViewModel.nitro';
 import type { UseRiveListResult } from '../types';
+import { useDisposableMemo } from './useDisposableMemo';
 
 /**
  * Hook for interacting with list ViewModel instance properties.
@@ -22,10 +23,14 @@ export function useRiveList(
     setError(null);
   }, [path, viewModelInstance]);
 
-  const property = useMemo(() => {
-    if (!viewModelInstance) return undefined;
-    return viewModelInstance.listProperty(path);
-  }, [viewModelInstance, path]);
+  const property = useDisposableMemo(
+    () => {
+      if (!viewModelInstance) return undefined;
+      return viewModelInstance.listProperty(path);
+    },
+    (p) => p?.dispose(),
+    [viewModelInstance, path]
+  );
 
   useEffect(() => {
     if (viewModelInstance && !property) {
@@ -45,7 +50,6 @@ export function useRiveList(
     return () => {
       removeListener();
       property.removeListeners();
-      property.dispose();
     };
   }, [property]);
 

src/hooks/useRiveProperty.ts

@@ -1,9 +1,10 @@
-import { useCallback, useEffect, useState, useMemo } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import {
   type ObservableProperty,
   type ViewModelInstance,
   type ViewModelProperty,
 } from '../specs/ViewModel.nitro';
+import { useDisposableMemo } from './useDisposableMemo';
 
 /**
  * Base hook for all ViewModelInstance property interactions.
@@ -34,13 +35,17 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
   Error | null,
   P | undefined,
 ] {
-  const property = useMemo(() => {
-    if (!viewModelInstance) return;
-    return options.getProperty(
-      viewModelInstance,
-      path
-    ) as unknown as ObservableViewModelProperty<T>;
-  }, [options, viewModelInstance, path]);
+  const property = useDisposableMemo(
+    () => {
+      if (!viewModelInstance) return undefined;
+      return options.getProperty(
+        viewModelInstance,
+        path
+      ) as unknown as ObservableViewModelProperty<T>;
+    },
+    (p) => p?.dispose(),
+    [options, viewModelInstance, path]
+  );
 
   // Always start undefined — the listener delivers the current value as its first emission.
   // (iOS experimental: via valueStream; iOS/Android legacy: emitted synchronously on subscribe)
@@ -82,7 +87,6 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
 
     return () => {
       removeListener();
-      property.dispose();
     };
   }, [options, property]);
 

src/hooks/useViewModelInstance.ts

@@ -1,11 +1,12 @@
 // TODO: migrate createInstance/createInstanceByName/etc to async equivalents
 /* eslint-disable @typescript-eslint/no-deprecated */
-import { useMemo, useEffect, useRef } from 'react';
+import { useMemo, useRef } from 'react';
 import type { ViewModel, ViewModelInstance } from '../specs/ViewModel.nitro';
 import type { RiveFile } from '../specs/RiveFile.nitro';
 import type { RiveViewRef } from '../index';
 import { callDispose } from '../core/callDispose';
 import { ArtboardByName } from '../specs/ArtboardBy';
+import { useDisposableMemo } from './useDisposableMemo';
 
 interface UseViewModelInstanceBaseParams {
   /**
@@ -336,49 +337,30 @@ export function useViewModelInstance(
   const required = params?.required ?? false;
   const onInit = params?.onInit;
 
-  const prevInstanceRef = useRef<{
-    instance: ViewModelInstance | null | undefined;
-    needsDispose: boolean;
-  } | null>(null);
+  const onInitRef = useRef(onInit);
+  onInitRef.current = onInit;
 
-  const result = useMemo(() => {
-    const created = createInstance(
-      source,
-      instanceName,
-      artboardName,
-      viewModelName,
-      useNew
-    );
-    if (created.instance && onInit) {
-      onInit(created.instance);
-    }
-    return created;
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- onInit excluded intentionally
-  }, [source, instanceName, artboardName, viewModelName, useNew]);
-
-  // Dispose previous instance if it changed and needed disposal
-  if (
-    prevInstanceRef.current &&
-    prevInstanceRef.current.instance !== result.instance &&
-    prevInstanceRef.current.needsDispose &&
-    prevInstanceRef.current.instance
-  ) {
-    callDispose(prevInstanceRef.current.instance);
-  }
-  prevInstanceRef.current = result;
-
-  // Cleanup on unmount
-  useEffect(() => {
-    return () => {
-      if (
-        prevInstanceRef.current?.needsDispose &&
-        prevInstanceRef.current.instance
-      ) {
-        callDispose(prevInstanceRef.current.instance);
-        prevInstanceRef.current = null;
+  const result = useDisposableMemo(
+    () => {
+      const created = createInstance(
+        source,
+        instanceName,
+        artboardName,
+        viewModelName,
+        useNew
+      );
+      if (created.instance && onInitRef.current) {
+        onInitRef.current(created.instance);
       }
-    };
-  }, []);
+      return created;
+    },
+    (r) => {
+      if (r.needsDispose && r.instance) {
+        callDispose(r.instance);
+      }
+    },
+    [source, instanceName, artboardName, viewModelName, useNew]
+  );
 
   const error = useMemo(
     () => (result.error ? new Error(result.error) : null),