[NateIsern]

Summary

Android native navigators cannot offer predictive Back when ReactActivity's completion-only JavaScript callback always owns Back. Add an explicit BackHandler.setNativeNavigationEnabled opt-in. Existing applications retain their current behavior. When enabled, registered JavaScript handlers conservatively own Back; with none, native navigators and Android can own the gesture.

Navigation libraries can retain an ordinary fallback handler in the JS dispatch chain while marking it as delegated to an equivalent ready native owner. Changing delegation preserves registration order. Thus an overlay returning false still reaches router navigation, and one returning true still consumes Back.

An Activity-scoped public coordinator lets native navigators observe ownership. It restores ownership after an unhandled JS event's bounded native fallback, scopes cleanup to the originating React context, releases destroyed Activity references, and retains state through Activity recreation. Native consumers must participate in this coordination; this API alone does not implement a navigation preview.

Changelog

[Android][Added] - Add opt-in native Back ownership that preserves JavaScript interception and navigation fallback.

Test plan

• Seven BackHandler behavioral Jest tests pass, including unknown handler true/false behavior, delegated fallback ordering, final-handler removal and opt-out. Mutating delegated fallback counting and handler ordering independently makes the relevant tests fail.
• ESLint passes for the changed JavaScript sources/tests.
• Generated public TypeScript snapshot validation and generated TypeScript type tests pass.
• The equivalent version-pinned 0.88.0 backport builds ReactAndroid Kotlin and Java from source using Expo's documented source-build configuration. Hermes is built from its pinned source; no precompiled ReactAndroid API substitution is used.
• Seven native tests pass against the source-built framework: four coordinator tests and three React module lifecycle tests, with no skips. The source distribution exposes testDebugUnitTest; Robolectric uses its exact Android 13 instrumented framework artifact, downloaded from official Maven Central and verified against the published SHA-512 because local Java HTTP cannot reach that repository.
• Device predictive-gesture acceptance and integration with native navigation libraries remain pending. This PR stays draft until that evidence is available.

Local build prerequisites: ICU development files for the host Hermes compiler; the existing Hermes archive-wrapper fix from #59589 is separately backported for the 0.88.0 build. Due to local Java HTTP download failures, exact upstream archives were fetched over HTTPS and SHA-256 verified before the normal extraction/compilation tasks. No TLS verification, compiler checks or tests were disabled.

[meta-cla]

Hi @NateIsern!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[github-actions]

Warning

JavaScript API change detected

This PR commits an update to ReactNativeApi.d.ts, indicating a change to React Native's public JavaScript API.

• Please include a clear changelog message.
• This change will be subject to additional review.

This change was flagged as: POTENTIALLY_BREAKING