Bartlomiej Bloniarz

This commit introduces a **critical null check** within the `updateProps` method of the **`SurfaceMountingManager`** in React Native's **Fabric mounting layer** for Android. It **prevents potential application crashes** that could occur if the `viewState` is unexpectedly null during property updates, a scenario observed with libraries like Reanimated. By using `getNullableViewState` and logging a soft exception instead of crashing, this **bug fix** significantly improves the **stability and robustness** of the rendering pipeline. This change also ensures **consistency** with similar null checks already present in related methods like `updateLayout`, enhancing overall system reliability.

This commit delivers a crucial **bug fix** addressing a **SIGSEGV crash** within the **Native Animated Nodes Manager** (`NativeAnimatedNodesManager`). The crash occurred when the manager was destroyed while the Choreographer thread was still firing animation frames, leading to `pullAnimationMutations` being called on a freed object due to an unsafe raw `this` pointer capture in the **Animation Backend** callback. To resolve this, `NativeAnimatedNodesManager` now inherits from `std::enable_shared_from_this`, enabling the callback to capture a `std::weak_ptr` to the manager. This change ensures that animation mutations are only processed if the manager instance remains valid, significantly enhancing the **stability** of React Native's native animation system.

This commit **adds new integration tests** to the **Animation Backend** within `react-native`, specifically located in `packages/react-native/Libraries/Animated/__tests__/AnimatedBackendSuspense-itest.js`. These **integration tests** are designed to verify that **native-driven animations** correctly preserve their state and continue running through **Suspense transitions** and `react-freeze` cycles. The work ensures animation state is maintained when components are suspended or undergo freezing, thereby **catching regressions** in the interaction between the **Animation Backend** and React's concurrent features. This **enhances the reliability** and stability of animations in complex React applications by validating their behavior under concurrent rendering conditions.

This commit **fixes a bug** in the **Animation Backend** that prevented correct JavaScript synchronization of animation state after main-thread commits. Previously, the `runtimeShadowNodeReference_` was not properly propagated, causing the `AnimatedPropsRegistry` to retain outdated values and leading to old style values reappearing on subsequent renders. The fix ensures correct `runtimeShadowNodeReference_` propagation and conditionally **cleans up the `AnimatedPropsRegistry`** after JS sync when the `updateRuntimeShadowNodeReferencesOnCommitThread` flag is enabled. This **maintenance** work improves the reliability of **animated value synchronization** to JavaScript, preventing visual inconsistencies. A new **integration test** was added to validate this corrected behavior.

This commit **adds new examples** to the **RNTester application** for both **Android and iOS**, specifically demonstrating the **layout-updating capabilities of the Shared Animation Backend** within the **Catalyst architecture**. This **enhances developer tooling** by providing practical, runnable examples that showcase how the animation backend handles layout changes. The addition of `AnimationBackendIndex` to `RNTesterList.android.js` and `RNTesterList.ios.js` facilitates easy access and testing of these new animation features, improving understanding and validation of the animation system.

This commit **adds comprehensive documentation** for the **Shared Animation Backend**, detailing its usage and design principles. A new markdown file, `AnimationBackend.md`, is introduced within the `packages/react-native/ReactCommon/react/renderer/animationbackend/__docs__` directory to house this content. Additionally, the main `__docs__/README.md` is updated to include a direct link to this new resource. This **documentation update** significantly improves the discoverability and understanding of the **Animation Backend** for developers, making it easier to integrate and comprehend its functionality.

This commit **refactors** the core animation timing mechanism within React Native to prevent platform-specific timestamp representation bugs. It introduces a new type, `AnimationTimestamp` (an alias for `std::chrono::duration<double, std::milli>`), to consistently represent animation frame times instead of simple `double` values. This change impacts the **Animation Backend**, **UIManager**, and **NativeAnimatedNodesManager**, updating various `onAnimationFrame` and related methods to use the new robust timestamp type. The primary goal is to ensure more **consistent and reliable animation timing** across all supported platforms.

This commit **refactors** the **animation system** by **decoupling `AnimationBackend` initialization** from `Animated` and moving it to the `Scheduler`. It introduces a new **`AnimationChoreographer` interface** for native animation frame scheduling, which is then passed to `UIManager` and `ReactHost`. This change improves the **modularity** of the animation pipeline, allowing animation frontends like `Animated` to obtain a reference to the backend for scheduling updates. The `React-Fabric` podspec is updated, and a `TesterAnimationChoreographer` is added for `fantom` tests, enhancing **testability** and the overall **architecture** of animation frame scheduling.

This commit introduces a **new capability** for **iOS and macOS animation management** by providing the `AnimationBackend` with its own dedicated `DisplayLink` instance. A new class, `RCTAnimationChoreographer`, is integrated into `RCTScheduler` to manage this display link, ensuring animations are synchronized independently. This **enhancement to the animation system** aims to improve the precision and reliability of animations on Apple platforms. The changes primarily affect `RCTScheduler.mm`, integrating `RCTAnimationChoreographer` and its `displayLinkTick` mechanism for more robust animation choreography.

This commit **refactors the Android animation system** by providing the `AnimationBackend` with its own dedicated `Choreographer` instance for managing animation frame callbacks. This change introduces new components like `AnimationBackendChoreographer` (Kotlin) and `AndroidAnimationChoreographer` (C++ JNI wrapper) to facilitate independent frame scheduling. The **Fabric UIManager** and **ReactInstance initialization** on Android are updated to integrate this new, isolated animation mechanism. This architectural improvement enhances the precision and control over **native animations on Android**, potentially leading to smoother and more reliable animation performance.

This commit **refactors** the **AnimationBackend** to ensure its `start` and `stop` methods, along with its internal callback list, are **thread-safe**. A `std::mutex` has been introduced to guard these operations, preventing potential race conditions when called concurrently from both the JavaScript and UI threads. This change enhances the **stability** and **reliability** of the **React Native animation system**, particularly for the `NativeAnimatedNodesManager` which now utilizes a new callback ID mechanism for managing animations. The update addresses potential concurrency issues, improving the overall robustness of animation lifecycle management within the renderer.

This commit introduces a **new capability** to manually trigger the **animation backend** from events, addressing a limitation where event-driven animation updates could be missed if they occurred outside the regular animation frame cycle. It adds a `trigger` method to the `AnimationBackend` interface and its implementations, which is then called by `NativeAnimatedNodesManager`'s `handleAnimatedEvent` to push immediate updates to the mounting layer. This ensures that **event-driven animations** are processed promptly, improving the responsiveness and correctness of animated interactions. The change primarily affects the **React Native animation system**, particularly how `Animated` components respond to user input or other asynchronous events.

This commit **refactors** the management of `ShadowNodeFamily` within the **React Native Animated module** to enhance animation reliability. It **moves the `ShadowNodeFamily` ownership** from a global map in `NativeAnimatedNodesManager` to be directly managed by individual `PropsAnimatedNode` instances. This change **fixes a bug** where `ShadowNodeFamily` connections were prematurely disconnected, causing animations to be wrongly skipped, especially when multiple `PropsAnimatedNode`s were associated with a single view. By delegating `connectToShadowNodeFamily` and `disconnectFromShadowNodeFamily` methods to `PropsAnimatedNode`, this ensures correct lifecycle management and is a critical step towards enabling the new **Animation Backend**.

This commit introduces a **new capability** to **synchronize final animated property values** from the native animation system back to the JavaScript thread's React state. It enables the **`animated` module** to schedule a commit on the JS thread at the conclusion of an animation, leveraging RSNRU to update `ShadowNode` references and ensure React components accurately reflect the final animated state. This involves adding `ShadowTreeCommitSource::AnimationEndSync` and new methods like `requestAsyncFlushForSurfaces` within the **animation backend** to facilitate this asynchronous property update. This **feature** significantly enhances the consistency between native animations and the React reconciliation process, preventing stale UI states after animations complete.

This commit **enhances the React Native animation backend** by integrating **synchronous property updates** into the `AnimatedPropsRegistry`. It ensures that fast-path updates, which bypass the ShadowTree, are correctly registered and merged into the `AnimatedPropsRegistry` via `getMap`, preventing them from being overwritten by subsequent React commits. This **new capability** involves **refactoring** the `AnimationBackend`'s `onAnimationFrame` and `commitUpdates` to process mutations based on `hasLayoutUpdates` and handle single surface updates. The `NativeAnimatedNodesManager` is also updated to correctly process these direct view property updates. This change improves the **reliability and correctness of animated non-layout props**, ensuring consistent visual behavior for components using synchronous animations.

This commit **enhances the testing suite** for the **`AnimatedBackend`** within **React Native's `Animated` library**. It introduces a **new integration test** in `AnimatedBackend-itest.js` to specifically verify the correct simultaneous animation of `width`, `height`, and `opacity` properties using `Animated.parallel`. This **testing enhancement** improves the **reliability and stability** of the animation system by ensuring these fundamental concurrent animations function as expected, preventing potential regressions in core UI animation capabilities.

This commit **refactors** the **C++ animated module** to directly pass `folly::dynamic` objects for animation updates to the **Animation Backend**, reverting a temporary change that used `AnimatedProps` for testing. Specifically, `NativeAnimatedNodesManager` now sends calculated `folly::dynamic` props without repacking, while the `AnimationBackend` and `AnimatedPropsRegistry` are updated to efficiently process and merge these raw dynamic properties. This **improves performance** by streamlining the data flow and avoiding unnecessary data transformations within the animation system. The change ensures the current C++ animated implementation operates optimally by leveraging `folly::dynamic` for property updates.

This commit introduces the **`AnimationBackendCommitHook`** and **`AnimatedPropsRegistry`** to significantly improve how **React Native's animation backend** synchronizes with the React renderer. This **new capability** provides a mechanism to reconcile animated property updates, which might originate outside of React's rendering cycle, with React's internal ShadowTree state. By intercepting React commits before the layout phase, the hook ensures that the UI accurately reflects the current animated state, preventing lost updates and visual inconsistencies. This **refactoring** addresses a critical issue in complex animation scenarios, particularly for libraries like Reanimated, by ensuring React's internal state always reflects the true animated properties.

This commit introduces a **new capability** to the **React Native C++ Native Animated module**, enabling it to leverage **Fabric's `ShadowNodeFamily`** instances for more efficient and accurate animation updates. It allows the `AnimationBackend` to utilize the `cloneMultiple` method when pushing updates through the `ShadowTree`, which is crucial for animating layout properties. A new method, `connectAnimatedNodeToShadowNodeFamily`, has been added across the `NativeAnimatedModule`, `NativeAnimatedTurboModule`, and `NativeAnimatedNodesManager` to facilitate this integration. This **enhancement** significantly improves the **performance and correctness of native animations** that affect view layout, ensuring better synchronization with the Fabric rendering pipeline.

This commit performs a **refactoring** within the **React Native animation backend** by extracting the `cloneProp` helper function. Previously embedded in `AnimationBackend.cpp`, this logic has been moved to `AnimatedProps.h` to enable **code reusability** across the animation system. The `AnimationBackend::cloneProps` function now delegates its prop cloning responsibilities to this newly exposed helper, improving the modularity and maintainability of the animation system's property handling. This change primarily impacts the internal structure of the animation backend, making its property cloning mechanism more accessible and organized for future development.