@rive-app/react-native 0.1.5 → 0.2.1

package/nitrogen/generated/shared/c++/UnifiedRiveEvent.hpp

@@ -2,7 +2,7 @@
 /// UnifiedRiveEvent.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
-/// Copyright © 2026 Marc Rousavy @ Margelo
+/// Copyright © Marc Rousavy @ Margelo
 ///
 
 #pragma once
@@ -22,6 +22,11 @@
 #else
 #error NitroModules cannot be found! Are you sure you installed NitroModules properly?
 #endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
 
 // Forward declaration of `RiveEventType` to properly resolve imports.
 namespace margelo::nitro::rive { enum class RiveEventType; }
@@ -37,7 +42,7 @@ namespace margelo::nitro::rive {
   /**
    * A struct which can be represented as a JavaScript object (UnifiedRiveEvent).
    */
-  struct UnifiedRiveEvent {
+  struct UnifiedRiveEvent final {
   public:
     std::string name     SWIFT_PRIVATE;
     RiveEventType type     SWIFT_PRIVATE;
@@ -49,6 +54,9 @@ namespace margelo::nitro::rive {
   public:
     UnifiedRiveEvent() = default;
     explicit UnifiedRiveEvent(std::string name, RiveEventType type, std::optional<double> delay, std::optional<std::unordered_map<std::string, std::variant<bool, std::string, double>>> properties, std::optional<std::string> url, std::optional<std::string> target): name(name), type(type), delay(delay), properties(properties), url(url), target(target) {}
+
+  public:
+    friend bool operator==(const UnifiedRiveEvent& lhs, const UnifiedRiveEvent& rhs) = default;
   };
 
 } // namespace margelo::nitro::rive
@@ -61,22 +69,22 @@ namespace margelo::nitro {
     static inline margelo::nitro::rive::UnifiedRiveEvent fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
       jsi::Object obj = arg.asObject(runtime);
       return margelo::nitro::rive::UnifiedRiveEvent(
-        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, "name")),
-        JSIConverter<margelo::nitro::rive::RiveEventType>::fromJSI(runtime, obj.getProperty(runtime, "type")),
-        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, "delay")),
-        JSIConverter<std::optional<std::unordered_map<std::string, std::variant<bool, std::string, double>>>>::fromJSI(runtime, obj.getProperty(runtime, "properties")),
-        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, "url")),
-        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, "target"))
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "name"))),
+        JSIConverter<margelo::nitro::rive::RiveEventType>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "type"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "delay"))),
+        JSIConverter<std::optional<std::unordered_map<std::string, std::variant<bool, std::string, double>>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "properties"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "url"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "target")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::rive::UnifiedRiveEvent& arg) {
       jsi::Object obj(runtime);
-      obj.setProperty(runtime, "name", JSIConverter<std::string>::toJSI(runtime, arg.name));
-      obj.setProperty(runtime, "type", JSIConverter<margelo::nitro::rive::RiveEventType>::toJSI(runtime, arg.type));
-      obj.setProperty(runtime, "delay", JSIConverter<std::optional<double>>::toJSI(runtime, arg.delay));
-      obj.setProperty(runtime, "properties", JSIConverter<std::optional<std::unordered_map<std::string, std::variant<bool, std::string, double>>>>::toJSI(runtime, arg.properties));
-      obj.setProperty(runtime, "url", JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.url));
-      obj.setProperty(runtime, "target", JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.target));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "name"), JSIConverter<std::string>::toJSI(runtime, arg.name));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "type"), JSIConverter<margelo::nitro::rive::RiveEventType>::toJSI(runtime, arg.type));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "delay"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.delay));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "properties"), JSIConverter<std::optional<std::unordered_map<std::string, std::variant<bool, std::string, double>>>>::toJSI(runtime, arg.properties));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "url"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.url));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "target"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.target));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -87,12 +95,12 @@ namespace margelo::nitro {
       if (!nitro::isPlainObject(runtime, obj)) {
         return false;
       }
-      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, "name"))) return false;
-      if (!JSIConverter<margelo::nitro::rive::RiveEventType>::canConvert(runtime, obj.getProperty(runtime, "type"))) return false;
-      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, "delay"))) return false;
-      if (!JSIConverter<std::optional<std::unordered_map<std::string, std::variant<bool, std::string, double>>>>::canConvert(runtime, obj.getProperty(runtime, "properties"))) return false;
-      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, "url"))) return false;
-      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, "target"))) return false;
+      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "name")))) return false;
+      if (!JSIConverter<margelo::nitro::rive::RiveEventType>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "type")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "delay")))) return false;
+      if (!JSIConverter<std::optional<std::unordered_map<std::string, std::variant<bool, std::string, double>>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "properties")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "url")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "target")))) return false;
       return true;
     }
   };

package/nitrogen/generated/shared/c++/views/HybridRiveViewComponent.cpp

@@ -2,7 +2,7 @@
 /// HybridRiveViewComponent.cpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
-/// Copyright © 2026 Marc Rousavy @ Margelo
+/// Copyright © Marc Rousavy @ Margelo
 ///
 
 #include "HybridRiveViewComponent.hpp"
@@ -12,6 +12,7 @@
 #include <utility>
 #include <NitroModules/NitroDefines.hpp>
 #include <NitroModules/JSIConverter.hpp>
+#include <NitroModules/PropNameIDCache.hpp>
 #include <react/renderer/core/RawValue.h>
 #include <react/renderer/core/ShadowNode.h>
 #include <react/renderer/core/ComponentDescriptor.h>
@@ -110,7 +111,7 @@ namespace margelo::nitro::rive::views {
         const react::RawValue* rawValue = rawProps.at("onError", nullptr, nullptr);
         if (rawValue == nullptr) return sourceProps.onError;
         const auto& [runtime, value] = (std::pair<jsi::Runtime*, jsi::Value>)*rawValue;
-        return CachedProp<std::function<void(const RiveError& /* error */)>>::fromRawValue(*runtime, value.asObject(*runtime).getProperty(*runtime, "f"), sourceProps.onError);
+        return CachedProp<std::function<void(const RiveError& /* error */)>>::fromRawValue(*runtime, value.asObject(*runtime).getProperty(*runtime, PropNameIDCache::get(*runtime, "f")), sourceProps.onError);
       } catch (const std::exception& exc) {
         throw std::runtime_error(std::string("RiveView.onError: ") + exc.what());
       }
@@ -120,7 +121,7 @@ namespace margelo::nitro::rive::views {
         const react::RawValue* rawValue = rawProps.at("hybridRef", nullptr, nullptr);
         if (rawValue == nullptr) return sourceProps.hybridRef;
         const auto& [runtime, value] = (std::pair<jsi::Runtime*, jsi::Value>)*rawValue;
-        return CachedProp<std::optional<std::function<void(const std::shared_ptr<HybridRiveViewSpec>& /* ref */)>>>::fromRawValue(*runtime, value.asObject(*runtime).getProperty(*runtime, "f"), sourceProps.hybridRef);
+        return CachedProp<std::optional<std::function<void(const std::shared_ptr<HybridRiveViewSpec>& /* ref */)>>>::fromRawValue(*runtime, value.asObject(*runtime).getProperty(*runtime, PropNameIDCache::get(*runtime, "f")), sourceProps.hybridRef);
       } catch (const std::exception& exc) {
         throw std::runtime_error(std::string("RiveView.hybridRef: ") + exc.what());
       }

package/nitrogen/generated/shared/c++/views/HybridRiveViewComponent.hpp

@@ -2,7 +2,7 @@
 /// HybridRiveViewComponent.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
-/// Copyright © 2026 Marc Rousavy @ Margelo
+/// Copyright © Marc Rousavy @ Margelo
 ///
 
 #pragma once

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rive-app/react-native",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Rive React Native",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -91,12 +91,12 @@
     "eslint-plugin-jest": "^29.1.0",
     "eslint-plugin-prettier": "^5.2.3",
     "jest": "^29.7.0",
-    "nitrogen": "0.31.10",
+    "nitrogen": "0.33.2",
     "prettier": "^3.0.3",
     "react": "19.0.0",
     "react-native": "0.79.2",
     "react-native-builder-bob": "^0.40.10",
-    "react-native-nitro-modules": "0.31.10",
+    "react-native-nitro-modules": "0.33.2",
     "react-test-renderer": "19.0.0",
     "release-it": "^17.10.0",
     "turbo": "^1.10.7",
@@ -105,7 +105,7 @@
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
-    "react-native-nitro-modules": ">=0.31.8"
+    "react-native-nitro-modules": ">=0.33.2"
   },
   "workspaces": [
     "example",

package/src/core/RiveFile.ts

@@ -123,7 +123,7 @@ export namespace RiveFileFactory {
 
     if (!assetURI) {
       throw new Error(
-        `Invalid source provided, ${source} is not a valid asset ID or URI`
+        `Invalid source: could not resolve asset ${source}. Ensure 'riv' is in metro.config.js assetExts.`
       );
     }
 

package/src/hooks/useViewModelInstance.ts

@@ -3,16 +3,9 @@ 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';
 
-export interface UseViewModelInstanceParams {
-  /**
-   * Get a specifically named instance from the ViewModel.
-   */
-  name?: string;
-  /**
-   * Create a new (blank) instance from the ViewModel.
-   */
-  useNew?: boolean;
+interface UseViewModelInstanceBaseParams {
   /**
    * If true, throws an error when the instance cannot be obtained.
    * This is useful with Error Boundaries and ensures TypeScript knows
@@ -27,27 +20,93 @@ export interface UseViewModelInstanceParams {
   onInit?: (instance: ViewModelInstance) => void;
 }
 
+interface UseViewModelInstanceFileBaseParams
+  extends UseViewModelInstanceBaseParams {
+  /**
+   * The ViewModel instance name (uses `createInstanceByName()`).
+   * If not provided, creates the default instance.
+   */
+  instanceName?: string;
+}
+
+/**
+ * Use the ViewModel assigned to the default artboard.
+ */
+interface UseViewModelInstanceFileDefault
+  extends UseViewModelInstanceFileBaseParams {
+  artboardName?: never;
+  viewModelName?: never;
+}
+
+/**
+ * Use the ViewModel assigned to a specific artboard.
+ */
+interface UseViewModelInstanceFileByArtboard
+  extends UseViewModelInstanceFileBaseParams {
+  /**
+   * Get the ViewModel assigned to this artboard.
+   */
+  artboardName: string;
+  viewModelName?: never;
+}
+
+/**
+ * Use a ViewModel by name (file-wide lookup).
+ * ViewModels are defined at the file level, not per-artboard.
+ */
+interface UseViewModelInstanceFileByViewModelName
+  extends UseViewModelInstanceFileBaseParams {
+  artboardName?: never;
+  /**
+   * The name of the ViewModel to use (uses `viewModelByName()`).
+   * ViewModels are defined at the file level and looked up by name across the entire file.
+   */
+  viewModelName: string;
+}
+
+export type UseViewModelInstanceFileParams =
+  | UseViewModelInstanceFileDefault
+  | UseViewModelInstanceFileByArtboard
+  | UseViewModelInstanceFileByViewModelName;
+
+export interface UseViewModelInstanceViewModelParams
+  extends UseViewModelInstanceBaseParams {
+  /**
+   * The ViewModel instance name (uses `createInstanceByName()`).
+   * If not provided, creates the default instance.
+   */
+  name?: string;
+  /**
+   * Create a new (blank) instance from the ViewModel.
+   */
+  useNew?: boolean;
+}
+
+export type UseViewModelInstanceRefParams = UseViewModelInstanceBaseParams;
+
 type ViewModelSource = ViewModel | RiveFile | RiveViewRef;
 
 function isRiveViewRef(source: ViewModelSource | null): source is RiveViewRef {
-  return (
-    source !== null && source !== undefined && 'getViewModelInstance' in source
-  );
+  return source !== null && 'getViewModelInstance' in source;
 }
 
 function isRiveFile(source: ViewModelSource | null): source is RiveFile {
-  return (
-    source !== null &&
-    source !== undefined &&
-    'defaultArtboardViewModel' in source
-  );
+  return source !== null && 'defaultArtboardViewModel' in source;
 }
 
+type CreateInstanceResult = {
+  instance: ViewModelInstance | null;
+  needsDispose: boolean;
+  error?: string;
+};
+
 function createInstance(
   source: ViewModelSource | null,
-  name: string | undefined,
+  instanceName: string | undefined,
+  artboardName: string | undefined,
+  viewModelName: string | undefined,
   useNew: boolean
-): { instance: ViewModelInstance | null; needsDispose: boolean } {
+): CreateInstanceResult {
   if (!source) {
     return { instance: null, needsDispose: false };
   }
@@ -58,15 +117,55 @@ function createInstance(
   }
 
   if (isRiveFile(source)) {
-    const viewModel = source.defaultArtboardViewModel();
-    const vmi = viewModel?.createDefaultInstance();
+    let viewModel: ViewModel | undefined;
+    if (viewModelName) {
+      viewModel = source.viewModelByName(viewModelName);
+      if (!viewModel) {
+        return {
+          instance: null,
+          needsDispose: false,
+          error: `ViewModel '${viewModelName}' not found`,
+        };
+      }
+    } else {
+      viewModel = source.defaultArtboardViewModel(
+        artboardName ? ArtboardByName(artboardName) : undefined
+      );
+      if (!viewModel) {
+        if (artboardName) {
+          return {
+            instance: null,
+            needsDispose: false,
+            error: `Artboard '${artboardName}' not found or has no ViewModel`,
+          };
+        }
+        return { instance: null, needsDispose: false };
+      }
+    }
+    const vmi = instanceName
+      ? viewModel.createInstanceByName(instanceName)
+      : viewModel.createDefaultInstance();
+    if (!vmi && instanceName) {
+      return {
+        instance: null,
+        needsDispose: false,
+        error: `ViewModel instance '${instanceName}' not found`,
+      };
+    }
     return { instance: vmi ?? null, needsDispose: true };
   }
 
   // ViewModel source
   let vmi: ViewModelInstance | undefined;
-  if (name) {
-    vmi = source.createInstanceByName(name);
+  if (instanceName) {
+    vmi = source.createInstanceByName(instanceName);
+    if (!vmi) {
+      return {
+        instance: null,
+        needsDispose: false,
+        error: `ViewModel instance '${instanceName}' not found`,
+      };
+    }
   } else if (useNew) {
     vmi = source.createInstance();
   } else {
@@ -79,7 +178,7 @@ function createInstance(
  * Hook for getting a ViewModelInstance from a RiveFile, ViewModel, or RiveViewRef.
  *
  * @param source - The RiveFile, ViewModel, or RiveViewRef to get an instance from
- * @param params - Configuration for which instance to retrieve (only used with ViewModel)
+ * @param params - Configuration for which instance to retrieve
  * @returns The ViewModelInstance or null if not found
  *
  * @example
@@ -91,6 +190,27 @@ function createInstance(
  *
  * @example
  * ```tsx
+ * // From RiveFile with specific instance name
+ * const { riveFile } = useRiveFile(require('./animation.riv'));
+ * const instance = useViewModelInstance(riveFile, { instanceName: 'PersonInstance' });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // From RiveFile with specific ViewModel name
+ * const { riveFile } = useRiveFile(require('./animation.riv'));
+ * const instance = useViewModelInstance(riveFile, { viewModelName: 'Settings' });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // From RiveFile with specific artboard
+ * const { riveFile } = useRiveFile(require('./animation.riv'));
+ * const instance = useViewModelInstance(riveFile, { artboardName: 'MainArtboard' });
+ * ```
+ *
+ * @example
+ * ```tsx
  * // From RiveViewRef (get auto-bound instance)
  * const { riveViewRef, setHybridRef } = useRive();
  * const instance = useViewModelInstance(riveViewRef);
@@ -129,20 +249,55 @@ function createInstance(
  * // Values are already set here
  * ```
  */
+// RiveFile overloads
 export function useViewModelInstance(
-  source: ViewModelSource,
-  params: UseViewModelInstanceParams & { required: true }
+  source: RiveFile,
+  params: UseViewModelInstanceFileParams & { required: true }
 ): ViewModelInstance;
 export function useViewModelInstance(
-  source: ViewModelSource | null,
-  params?: UseViewModelInstanceParams
+  source: RiveFile | null,
+  params?: UseViewModelInstanceFileParams
+): ViewModelInstance | null;
+
+// ViewModel overloads
+export function useViewModelInstance(
+  source: ViewModel,
+  params: UseViewModelInstanceViewModelParams & { required: true }
+): ViewModelInstance;
+export function useViewModelInstance(
+  source: ViewModel | null,
+  params?: UseViewModelInstanceViewModelParams
 ): ViewModelInstance | null;
+
+// RiveViewRef overloads
+export function useViewModelInstance(
+  source: RiveViewRef,
+  params: UseViewModelInstanceRefParams & { required: true }
+): ViewModelInstance;
+export function useViewModelInstance(
+  source: RiveViewRef | null,
+  params?: UseViewModelInstanceRefParams
+): ViewModelInstance | null;
+
+// Implementation
 export function useViewModelInstance(
   source: ViewModelSource | null,
-  params?: UseViewModelInstanceParams
+  params?:
+    | UseViewModelInstanceFileParams
+    | UseViewModelInstanceViewModelParams
+    | UseViewModelInstanceRefParams
 ): ViewModelInstance | null {
-  const name = params?.name;
-  const useNew = params?.useNew ?? false;
+  const fileInstanceName = (params as { instanceName?: string } | undefined)
+    ?.instanceName;
+  const viewModelInstanceName = (params as { name?: string } | undefined)?.name;
+  const instanceName = fileInstanceName ?? viewModelInstanceName;
+  const artboardName = (params as UseViewModelInstanceFileParams | undefined)
+    ?.artboardName;
+  const viewModelName = (params as UseViewModelInstanceFileParams | undefined)
+    ?.viewModelName;
+  const useNew =
+    (params as UseViewModelInstanceViewModelParams | undefined)?.useNew ??
+    false;
   const required = params?.required ?? false;
   const onInit = params?.onInit;
 
@@ -152,13 +307,19 @@ export function useViewModelInstance(
   } | null>(null);
 
   const result = useMemo(() => {
-    const created = createInstance(source, name, useNew);
+    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, name, useNew]);
+  }, [source, instanceName, artboardName, viewModelName, useNew]);
 
   // Dispose previous instance if it changed and needed disposal
   if (
@@ -186,8 +347,10 @@ export function useViewModelInstance(
 
   if (required && result.instance === null) {
     throw new Error(
-      'useViewModelInstance: Failed to get ViewModelInstance. ' +
-        'Ensure the source has a valid ViewModel and instance available.'
+      result.error
+        ? `useViewModelInstance: ${result.error}`
+        : 'useViewModelInstance: Failed to get ViewModelInstance. ' +
+          'Ensure the source has a valid ViewModel and instance available.'
     );
   }