From 1c17a9652e925574568986edcad34df67489ac69 Mon Sep 17 00:00:00 2001
From: CI <pggordonhayes@gmail.com>
Date: Wed, 19 Nov 2025 11:39:32 +0100
Subject: [PATCH 1/3] chore: prefer term graphic over animation

---
 example/src/pages/OutOfBandAssets.tsx    |  4 ++--
 example/src/pages/RiveTextRunExample.tsx |  2 +-
 src/core/RiveFile.ts                     | 14 +++++++-------
 src/index.tsx                            |  6 +++---
 4 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/example/src/pages/OutOfBandAssets.tsx b/example/src/pages/OutOfBandAssets.tsx
index 15d7ce25..f6860c30 100644
--- a/example/src/pages/OutOfBandAssets.tsx
+++ b/example/src/pages/OutOfBandAssets.tsx
@@ -63,7 +63,7 @@ export default function StateMachine() {
       <RiveView
         file={riveFile}
         fit={Fit.Contain}
-        style={styles.animation}
+        style={styles.rive}
         stateMachineName="State Machine 1"
         // The `referencedAssets` prop allows you to load external assets from various sources:
         // - A URI
@@ -122,7 +122,7 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'flex-start',
   },
-  animation: {
+  rive: {
     width: '100%',
     height: 400,
   },
diff --git a/example/src/pages/RiveTextRunExample.tsx b/example/src/pages/RiveTextRunExample.tsx
index 48a34275..0d0fc3a8 100644
--- a/example/src/pages/RiveTextRunExample.tsx
+++ b/example/src/pages/RiveTextRunExample.tsx
@@ -83,5 +83,5 @@ const styles = StyleSheet.create({
 TextRunExample.metadata = {
   name: 'Text Run',
   description:
-    'Demonstrates getting and setting text run values in Rive animations',
+    'Demonstrates getting and setting text run values in Rive graphics',
 } satisfies Metadata;
diff --git a/src/core/RiveFile.ts b/src/core/RiveFile.ts
index 3d9a3b1a..364e901f 100644
--- a/src/core/RiveFile.ts
+++ b/src/core/RiveFile.ts
@@ -14,12 +14,12 @@ const RiveFileInternal =
 
 /**
  * Factory namespace for creating RiveFile instances from different sources.
- * Provides static methods to load Rive animations from URLs, resources, or raw bytes.
+ * Provides static methods to load Rive files from URLs, resources, or raw bytes.
  */
 export namespace RiveFileFactory {
   /**
    * Creates a RiveFile instance from a URL.
-   * @param url - The URL of the Rive animation file
+   * @param url - The URL of the Rive (.riv) file
    * @param loadCdn - Whether to load from CDN (default: true)
    * @returns Promise that resolves to a RiveFile instance
    */
@@ -37,7 +37,7 @@ export namespace RiveFileFactory {
 
   /**
    * Creates a RiveFile instance from a local file path URL.
-   * @param pathURL - The local file path of the Rive animation file
+   * @param pathURL - The local file path of the Rive (.riv) file
    * @param loadCdn - Whether to load from CDN (default: true)
    * @returns Promise that resolves to a RiveFile instance
    */
@@ -73,7 +73,7 @@ export namespace RiveFileFactory {
 
   /**
    * Creates a RiveFile instance from raw bytes.
-   * @param bytes - The raw bytes of the Rive animation file
+   * @param bytes - The raw bytes of the Rive (.riv) file
    * @param loadCdn - Whether to load from CDN (default: true)
    * @returns Promise that resolves to a RiveFile instance
    */
@@ -97,13 +97,13 @@ export namespace RiveFileFactory {
    * @throws Error if the source is invalid or cannot be resolved
    * @example
    * // Using a resource ID
-   * const riveFile1 = await RiveFileFactory.fromSource(require('./animation.riv'));
+   * const riveFile1 = await RiveFileFactory.fromSource(require('./your_file.riv'));
    *
    * // Using a URI object
-   * const riveFile2 = await RiveFileFactory.fromSource({ uri: 'https://example.com/animation.riv' });
+   * const riveFile2 = await RiveFileFactory.fromSource({ uri: 'https://example.com/your_file.riv' });
    *
    * // Using a local file URI
-   * const riveFile3 = await RiveFileFactory.fromSource({ uri: 'file:///path/to/animation.riv' });
+   * const riveFile3 = await RiveFileFactory.fromSource({ uri: 'file:///path/to/your_file.riv' });
    *
    * @note To use .riv files with require(), you need to add 'riv' to the asset extensions in your metro.config.js:
    * ```js
diff --git a/src/index.tsx b/src/index.tsx
index 02d369be..7b8bdf1a 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -28,7 +28,7 @@ export function multiply(a: number, b: number): number {
 }
 
 /**
- * RiveView is a React Native component that renders Rive animations.
+ * RiveView is a React Native component that renders Rive graphics.
  * It provides a seamless way to display and control Rive graphics in your app.
  *
  * @example
@@ -53,8 +53,8 @@ export function multiply(a: number, b: number): number {
  * @property {Object} [style] - React Native style object for container customization
  *
  * The component also exposes methods for controlling playback:
- * - play(): Starts playing the animation
- * - pause(): Pauses the animation
+ * - play(): Starts playing the Rive graphic
+ * - pause(): Pauses the Rive graphic
  */
 export const RiveView = getHostComponent<RiveViewProps, RiveViewMethods>(
   'RiveView',

From 9129a924bf205329dd2146885eeb1461cec95bcc Mon Sep 17 00:00:00 2001
From: CI <pggordonhayes@gmail.com>
Date: Wed, 19 Nov 2025 11:39:49 +0100
Subject: [PATCH 2/3] docs: add deprecated warning

---
 example/src/pages/RiveEventsExample.tsx             | 7 +++++++
 example/src/pages/RiveStateMachineInputsExample.tsx | 7 +++++++
 example/src/pages/RiveTextRunExample.tsx            | 7 +++++++
 3 files changed, 21 insertions(+)

diff --git a/example/src/pages/RiveEventsExample.tsx b/example/src/pages/RiveEventsExample.tsx
index 5284914b..486a6df7 100644
--- a/example/src/pages/RiveEventsExample.tsx
+++ b/example/src/pages/RiveEventsExample.tsx
@@ -10,6 +10,13 @@ import {
 } from 'react-native-rive';
 import { type Metadata } from '../helpers/metadata';
 
+/**
+ * @deprecated Rive events at runtime is deprecated. Use data binding instead.
+ *
+ * See https://rive.app/docs/runtimes/data-binding
+ *
+ * Demonstrates getting and handling Rive events
+ */
 export default function EventsExample() {
   const { riveViewRef, setHybridRef } = useRive();
   const { riveFile, isLoading, error } = useRiveFile(
diff --git a/example/src/pages/RiveStateMachineInputsExample.tsx b/example/src/pages/RiveStateMachineInputsExample.tsx
index 85c80c09..673d8ffe 100644
--- a/example/src/pages/RiveStateMachineInputsExample.tsx
+++ b/example/src/pages/RiveStateMachineInputsExample.tsx
@@ -3,6 +3,13 @@ import { useEffect } from 'react';
 import { Fit, RiveView, useRive, useRiveFile } from 'react-native-rive';
 import { type Metadata } from '../helpers/metadata';
 
+/**
+ * @deprecated Setting state machine inputs at runtime is deprecated. Use data binding instead.
+ *
+ * See https://rive.app/docs/runtimes/data-binding
+ *
+ * Demonstrates getting and setting state machine inputs programmatically
+ */
 export default function StateMachineInputsExample() {
   const { riveViewRef, setHybridRef } = useRive();
   const { riveFile, isLoading, error } = useRiveFile(
diff --git a/example/src/pages/RiveTextRunExample.tsx b/example/src/pages/RiveTextRunExample.tsx
index 0d0fc3a8..d063c2c4 100644
--- a/example/src/pages/RiveTextRunExample.tsx
+++ b/example/src/pages/RiveTextRunExample.tsx
@@ -3,6 +3,13 @@ import { useEffect } from 'react';
 import { Fit, RiveView, useRive, useRiveFile } from 'react-native-rive';
 import { type Metadata } from '../helpers/metadata';
 
+/**
+ * @deprecated Setting text run values is deprecated. Use data binding instead.
+ *
+ * See https://rive.app/docs/runtimes/data-binding
+ *
+ * Demonstrates getting and setting text run values in Rive graphics
+ */
 export default function TextRunExample() {
   const { riveViewRef, setHybridRef } = useRive();
   const { riveFile, isLoading, error } = useRiveFile(

From 739bec7de94eb10439c80a9b40ab912e13250124 Mon Sep 17 00:00:00 2001
From: CI <pggordonhayes@gmail.com>
Date: Wed, 19 Nov 2025 12:24:16 +0100
Subject: [PATCH 3/3] docs: not on dev preview and updated roadmap

---
 README.md | 74 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 50 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index edb63bed..6def9d90 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,10 @@
 
 Rive React Native 2.0
 
+## Development Preview
+
+> **⚠️ Development Preview**: This package is currently in development preview. While it's functional and actively maintained, the API may change in future releases. We recommend testing thoroughly before using in production applications. We're actively gathering feedback to improve the library. Please share your thoughts and report any issues you encounter.
+
 ## Requirements
 
 - **React Native**: 0.78 or later (0.79+ recommended for better Android error messages)
@@ -79,7 +83,10 @@ Rive_RiveRuntimeAndroidVersion=10.6.0
 Use an inline config plugin in your `app.config.ts`:
 
 ```typescript
-import { withPodfileProperties, withGradleProperties } from '@expo/config-plugins';
+import {
+  withPodfileProperties,
+  withGradleProperties,
+} from '@expo/config-plugins';
 
 export default {
   expo: {
@@ -125,32 +132,51 @@ try {
 
 ## Feature Support
 
-The following runtime features are currently supported:
-
-✅ Supported | ⚠️ Partial | 🚧 In Development | ❌ Not Planned
-
-| Feature                    | Status | Description                                                      |
-| -------------------------- | ------ | ---------------------------------------------------------------- |
-| Artboard selection         | ✅     | Sepecify artboard to render                                      |
-| State machine selection    | ✅     | Specify a state machine to play                                  |
-| Animation selection        | ❌     | Animation playback not planned, use state machines               |
-| View autoPlay & play/pause | ✅     | Control view playback                                            |
-| Fit & Alignment            | ✅     | Fit modes supported, alignment coming soon                       |
-| Layout & Responsiveness    | ✅     | Basic responsive layouts supported                               |
-| Data Binding               | ⚠️     | Control data binding through runtime code                        |
-| Asset management           | 🚧     | Out-of-band assets not yet supported                             |
-| State machine inputs       | ✅     | Get/Set (nested) state machine inputs (legacy, see data binding) |
-| Text Runs                  | ✅     | Update (nested) text runs (legacy, see data binding)             |
-| Rive Events                | ✅     | Listen to Rive events                                            |
-| Rive Audio                 | ✅     | Full Rive audio playback supported                               |
-| `useRive()` hook           | ✅     | Convenient hook to access the Rive View ref after load           |
-| `useRiveFile()` hook       | ✅     | Convenient hook to load a Rive file                              |
-| `RiveView` error handling  | ✅     | Error handler for failed view operations                         |
-| `source` .riv file loading | ✅     | Conveniently load .riv files from JS source                      |
-| Renderer options           | ❌     | Single renderer option available (Rive)                          |
+This section provides a comprehensive overview of feature availability in `react-native-rive`, comparing it with the [previous Rive React Native runtime](https://github.com/rive-app/rive-react-native) and outlining the development roadmap.
+
+### Runtime Feature Comparison
+
+**Status Legend:** ✅ Supported | ⚠️ Partial | 🚧 In Development | ❌ Not Planned
+
+The following table compares feature availability with the [previous Rive React Native runtime](https://github.com/rive-app/rive-react-native).
+
+| Feature                           | Status | Description                                                      |
+| --------------------------------- | ------ | ---------------------------------------------------------------- |
+| Artboard selection                | ✅     | Specify artboard to render                                       |
+| State machine selection           | ✅     | Specify a state machine to play                                  |
+| View autoPlay & play/pause        | ✅     | Control view playback                                            |
+| Fit & Alignment                   | ✅     | Fit modes supported, alignment coming soon                       |
+| Layout & Responsiveness           | ✅     | Basic responsive layouts supported                               |
+| Data Binding                      | ✅     | Control data binding through runtime code                        |
+| Asset management                  | ✅     | Load assets out of band (referenced)                             |
+| State machine inputs (Deprecated) | ✅     | Get/Set (nested) state machine inputs (legacy, see data binding) |
+| Text Runs (Deprecated)            | ✅     | Update (nested) text runs (legacy, see data binding)             |
+| Rive Events (Deprecated)          | ✅     | Listen to Rive events                                            |
+| Rive Audio                        | ✅     | Rive audio playback supported                                    |
+| `useRive()` hook                  | ✅     | Convenient hook to access the Rive View ref after load           |
+| `useRiveFile()` hook              | ✅     | Convenient hook to load a Rive file                              |
+| `RiveView` error handling         | ✅     | Error handler for failed view operations                         |
+| `source` .riv file loading        | ✅     | Conveniently load .riv files from JS source                      |
+| Animation selection               | ❌     | Animation playback not planned, use state machines               |
+| Renderer options                  | ❌     | Single renderer option available (Rive)                          |
 
 > **Note**: Several features in the table above (state machine inputs, text runs, and events) represent legacy approaches to runtime control. We recommend using data binding instead, as it provides a more maintainable way to control your Rive graphics (both at edit time and runtime).
 
+### Roadmap
+
+**Status Legend:** ✅ Completed | 🚧 Planned |
+
+This section tracks new features and improvements planned for this runtime that were not available in the [previous Rive React Native runtime](https://github.com/rive-app/rive-react-native).
+
+| Feature                                                                                               | Status |
+| ----------------------------------------------------------------------------------------------------- | ------ |
+| [Reusable .riv File resources (preloading)](https://github.com/rive-app/rive-react-native/issues/260) | ✅     |
+| [Data Binding - Images](https://github.com/rive-app/rive-nitro-react-native/issues/9)                 | 🚧     |
+| [Data Binding - Artboards](https://github.com/rive-app/rive-nitro-react-native/issues/10)             | 🚧     |
+| [Data Binding - Lists](https://github.com/rive-app/rive-nitro-react-native/issues/11)                 | 🚧     |
+| [Data Binding - Value props](https://github.com/rive-app/rive-nitro-react-native/pull/24)             | 🚧     |
+| [Suspense](https://github.com/rive-app/rive-nitro-react-native/pull/19)                               | 🚧     |
+
 ## Contributing
 
 See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.