Android: stop re-arming the idle NATIVE_ANIMATED_MODULE Choreographer frame callback (behind feature flag)

[capt-muji]

Stop re-arming the idle NATIVE_ANIMATED_MODULE Choreographer frame callback (Android)

Part of #58367. Split from #58368 per review feedback (one PR per pump, each behind a feature flag).

Summary

NativeAnimatedModule's frame callback re-posts itself unconditionally at the end of every doFrameGuarded, so the NATIVE_ANIMATED_MODULE Choreographer callback runs at vsync rate forever — including while no animations are active.

This PR makes the re-post demand-gated, behind ReactNativeFeatureFlags.disableIdleNativeAnimatedFrameCallbackRearmAndroid (default false = current behavior; ossReleaseStage: 'experimental'). The callback stays armed only while hasActiveAnimations() is true, with two explicit re-arm points for animations being started:

1. didDispatchMountItems — animation operations (e.g. startAnimatingNode) execute in batches piggy-backed on mount-item dispatch; after executing a batch we re-arm unconditionally (the callback itself disarms on the next frame if nothing is actually active).
2. The operation-enqueue helpers (addOperation / addUnbatchedOperation / addPreOperation) — imperative JS animation calls can arrive from the native module thread when no mount items are pending at all; enqueueing re-arms the callback. ReactChoreographer.postFrameCallback hops to the UI thread internally, so this is safe from the module thread; enqueuedAnimationOnFrame is now @Volatile (it is written from both threads; the worst pre-existing race outcome is a redundant post).

Foregrounding / backgrounding

onHostResume → enqueueFrameCallback() and onHostPause/onHostDestroy → clearFrameCallback() are untouched. With the flag on, a resumed-but-idle app disarms after one frame with no active animations; the next animation operation re-arms.

Rollout

Flag: disableIdleNativeAnimatedFrameCallbackRearmAndroid — defaultValue: false, expectedReleaseValue: true, ossReleaseStage: 'experimental'. With the flag off, behavior is identical to current main.

Test plan

• Flag off (defaultValue): the unconditional enqueueFrameCallback() path is taken verbatim.
• Compiles: ./gradlew :packages:react-native:ReactAndroid:compileReleaseKotlin.
• Flag on, real app on device (OnePlus 3T, Android 9): idle adb shell atrace shows the NATIVE_ANIMATED_MODULE doFrames drop to ~0 while no animations run; starting an animation (Reanimated/Animated) arms it again and the animation completes; Animated.loop/repeat animations keep it armed continuously; pause/resume does not lose running animations.
• Flag on: RNTester native-animated integration tests pass.

Changelog:

[Android] [Fixed] - Stop re-arming the NATIVE_ANIMATED_MODULE Choreographer frame callback at vsync rate while no animations are active (behind disableIdleNativeAnimatedFrameCallbackRearmAndroid)

Prior art

The same gate was landed by #41606 (November 2023) and backed out by #41671 as "caused performace problems with react app". Mechanism differences and analysis: #58367.

[javache]

cc @zeyap - is this worth doing when C++ Animated is close to rolling out? Is the idle callback problem solved for C++ animated?

[capt-muji]

For @zeyap's question: when the C++ animated backend is enabled (cxxNativeAnimatedEnabled / mDriveCxxAnimations), animation driving goes through FabricUIManager.DispatchUIFrameCallback → mBinding.driveCxxAnimations() — that path is demand-gated by #58378, so it does not depend on this PR. This PR only affects the platform Kotlin NativeAnimatedModule implementation (used when the C++ backend is off), whose idle NATIVE_ANIMATED_MODULE callback still re-posts itself at vsync rate today.

[capt-muji]

On-device validation (OnePlus 3T, Android 9 / API 28, bridgeless Release)

Backported onto v0.86.3 (see the #58375 comment for why) with disableIdleNativeAnimatedFrameCallbackRearmAndroid forced ON, substituted into a real production app. Attributed every Choreographer post at idle via a diagnostic logging build.

Result: the legacy NativeAnimatedModule callback is disarmed at idle (0 posts — hasActiveAnimations() returned false and doFrameGuarded no longer self-re-arms). The operation-enqueue and didDispatchMountItems re-arm paths work; no starvation.

One thing worth flagging for @zeyap / @javache: Reanimated (com.swmansion.worklets.runloop.AnimationFrameQueue) reuses the NATIVE_ANIMATED_MODULE Choreographer callback-type slot for its own always-on worklet runloop. That activity stays armed at idle and in the background and is entirely separate from this PR (the flag does not — and should not — touch it). Anyone measuring 'NATIVE_ANIMATED_MODULE posts' at idle on a Reanimated app will see those, not this pump.

[capt-muji]

Prior-art note for reviewers landing here: #41606 landed essentially this same gate for NATIVE_ANIMATED_MODULE in November 2023 (skip the re-post when hasActiveAnimations() is false, behind enableOnDemandReactChoreographer) and was backed out days later by #41671 with the reason "caused performace problems with react app". Full analysis on the parent issue: #58367.

Mechanism difference

• Schedule a Choreographer callback only if there is ongoing animation #41606 armed exactly one re-arm trigger: OP_CODE_START_ANIMATING_NODE inside the Java operations loop.
• This PR re-arms from every operation enqueue path (addOperation, addUnbatchedOperation, addPreOperation) and again after each executed batch, so imperative JS animation calls that arrive while no mount items are pending still wake the callback.

Known remaining risk

This is the question @zeyap was cc'd for above: if the C++ shared animated backend drives animations that never surface through the Java nodesManager, this gate would disarm the slot underneath them, which would reproduce the old failure. If that is confirmed, this PR should not ship as-is. The other three slots in the family (#58375, #58376, #58378) are independent of that backend.

[capt-muji]

Audit note: the event-driven path (the gap class that plausibly broke #41606)

Finding: event dispatch does not depend on this frame callback.

• NativeAnimatedNodesManager.onEventDispatch hops to the UI thread
• handleEvent updates the value node and then calls updateNodes directly
• the new value therefore propagates to connected view props synchronously within the event hop

What still needs the frame callback: time-driven progression only, and every timed animation start routes through the operations queue (addOperation / addUnbatchedOperation), which this PR re-arms from.

The remaining open question is the C++ shared animated backend above.