fix!: useRiveProperty hooks start undefined, value delivered via listener

Author: mfazekas

src/hooks/__tests__/useRiveProperty.test.ts

@@ -17,6 +17,9 @@ describe('useRiveProperty', () => {
       },
       addListener: jest.fn((callback: (value: string) => void) => {
         listener = callback;
+        // Emit the current value immediately on subscribe, matching native behaviour:
+        // iOS legacy emits synchronously; experimental backend emits via valueStream.
+        callback(currentValue);
         return () => {
           listener = null;
         };
@@ -36,7 +39,9 @@ describe('useRiveProperty', () => {
     } as unknown as ViewModelInstance;
   };
 
-  it('should return initial value from property on first render', () => {
+  it('should return initial value delivered via listener (not from a sync read)', () => {
+    // Hooks always start undefined; the listener emits the current value immediately
+    // on subscribe (synchronously for legacy, via stream for experimental).
     const mockProperty = createMockProperty('Tea');
     const mockInstance = createMockViewModelInstance({
       'favDrink/type': mockProperty,
@@ -48,6 +53,8 @@ describe('useRiveProperty', () => {
       })
     );
 
+    // The mock's addListener emits 'Tea' synchronously — React batches it with the
+    // effect, so the value is available after renderHook (which wraps in act()).
     const [value] = result.current;
     expect(value).toBe('Tea');
   });

src/hooks/useRiveProperty.ts

@@ -34,7 +34,6 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
   Error | null,
   P | undefined,
 ] {
-  // Get the property first so we can read its initial value
   const property = useMemo(() => {
     if (!viewModelInstance) return;
     return options.getProperty(
@@ -43,17 +42,12 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
     ) as unknown as ObservableViewModelProperty<T>;
   }, [options, viewModelInstance, path]);
 
-  // Initialize state with property's current value (if available)
-  const [value, setValue] = useState<T | undefined>(() => property?.value);
+  // Always start undefined — the listener delivers the current value as its first emission.
+  // (iOS experimental: via valueStream; iOS/Android legacy: emitted synchronously on subscribe)
+  // This ensures consumers handle the loading state correctly on all backends.
+  const [value, setValue] = useState<T | undefined>(undefined);
   const [error, setError] = useState<Error | null>(null);
 
-  // Sync value when property reference changes (path or instance changed)
-  useEffect(() => {
-    if (property) {
-      setValue(property.value);
-    }
-  }, [property]);
-
   // Clear error when path or instance changes
   useEffect(() => {
     setError(null);
@@ -86,22 +80,22 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
     };
   }, [options, property]);
 
-  // Set the value of the property (no-op if property isn't available yet)
+  // Set the value of the property (no-op if property isn't available yet).
+  // Uses tracked `value` from state for updater functions — avoids a synchronous
+  // property.value read and is consistent with how React state works.
   const setPropertyValue = useCallback(
     (valueOrUpdater: T | ((prevValue: T | undefined) => T)) => {
       if (!property) {
         return;
       } else {
         const newValue =
           typeof valueOrUpdater === 'function'
-            ? (valueOrUpdater as (prevValue: T | undefined) => T)(
-                property.value
-              )
+            ? (valueOrUpdater as (prevValue: T | undefined) => T)(value)
             : valueOrUpdater;
         property.value = newValue;
       }
     },
-    [property]
+    [property, value]
   );
 
   return [value, setPropertyValue, error, property as unknown as P];