feat: make useRiveProperty start undefined and deliver value via listener

All backends now emit the current value as the first listener emission,
so hooks no longer need a synchronous property.value read on mount.

- useRiveProperty: always starts undefined; value arrives via the
  listener's first callback (not a sync read). Setter updater fn now
  uses tracked React state instead of property.value.
- iOS legacy: Number/String/Boolean/Enum addListener now emits the
  current value synchronously on subscribe, matching the stream-based
  behaviour of the experimental backend (valueStream) and Android
  (Flow with drop=0). No native changes needed elsewhere.
- Tests: mock addListener emits current value on subscribe; updated
  test description to reflect the new async-first semantics.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mfazekas

ios/legacy/HybridViewModelBooleanProperty.swift

@@ -18,4 +18,11 @@ class HybridViewModelBooleanProperty: HybridViewModelBooleanPropertySpec, Valued
       property.value = newValue
     }
   }
+
+  func addListener(onChanged: @escaping (Bool) -> Void) throws -> () -> Void {
+    // Emit current value immediately so the first subscription receives it,
+    // matching the stream-based behaviour of the experimental backend.
+    onChanged(value)
+    return helper.addListener(onChanged)
+  }
 }

ios/legacy/HybridViewModelEnumProperty.swift

@@ -18,4 +18,11 @@ class HybridViewModelEnumProperty: HybridViewModelEnumPropertySpec, ValuedProper
       property.value = newValue
     }
   }
+
+  func addListener(onChanged: @escaping (String) -> Void) throws -> () -> Void {
+    // Emit current value immediately so the first subscription receives it,
+    // matching the stream-based behaviour of the experimental backend.
+    onChanged(value)
+    return helper.addListener(onChanged)
+  }
 }

ios/legacy/HybridViewModelNumberProperty.swift

@@ -19,6 +19,9 @@ class HybridViewModelNumberProperty: HybridViewModelNumberPropertySpec, ValuedPr
   }
 
   func addListener(onChanged: @escaping (Double) -> Void) throws -> () -> Void {
+    // Emit current value immediately so the first subscription receives it,
+    // matching the stream-based behaviour of the experimental backend.
+    onChanged(value)
     return helper.addListener({ floatValue in onChanged(Double(floatValue)) })
   }
 }

ios/legacy/HybridViewModelStringProperty.swift

@@ -18,4 +18,11 @@ class HybridViewModelStringProperty: HybridViewModelStringPropertySpec, ValuedPr
       property.value = newValue
     }
   }
+
+  func addListener(onChanged: @escaping (String) -> Void) throws -> () -> Void {
+    // Emit current value immediately so the first subscription receives it,
+    // matching the stream-based behaviour of the experimental backend.
+    onChanged(value)
+    return helper.addListener(onChanged)
+  }
 }

src/hooks/__tests__/useRiveProperty.test.ts

@@ -15,8 +15,11 @@ describe('useRiveProperty', () => {
         currentValue = newValue;
         listener?.(newValue);
       },
+      // Emit the current value immediately on subscribe, matching native behaviour:
+      // iOS legacy emits synchronously; experimental backend emits via valueStream.
       addListener: jest.fn((callback: (value: string) => void) => {
         listener = callback;
+        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];