Support multiple Navigation 3 roots across Android lifecycle owners #6345

Summary

Extend the Android Navigation 3 integration to support applications with multiple NavDisplay and SentryNavEffect pairs hosted by different lifecycle owners.

Previously, the integration assumed that only one navigation root would be active at a time. In multi-Activity and multi-Fragment applications, overlapping navigation roots could overwrite or clear each other’s navigation state and tracing data.

Supported scenarios

• One NavDisplay and SentryNavEffect in a single Activity.
• One navigation pair per Activity in a multi-Activity app.
• One navigation pair per Fragment in a multi-Fragment app.
• Fragment pages in a ViewPager2, each with its own navigation pair.
• A navigation root beneath a DialogFragment or translucent Activity with its own navigation root.

Implementation

• Add NavLeaseCoordinator to select which eligible lifecycle owner may publish navigation state to the shared Sentry scope.
• Add lease-aware NavScopes and staged navigation data so inactive roots can retain state without overwriting the active root.
• Coordinate SentryNavEffect and back stack updates through the host lifecycle.
• Preserve and restore navigation transactions during lease handoffs.
• Clean up retained state when navigation roots are disposed or handoffs fail.
• Add unit and Robolectric integration coverage for Activities, Fragments, dialogs, and ViewPager2.
• Add runnable sample scenarios for multi-Activity and multi-Fragment applications.

Current limitations

The following scenarios remain unsupported:

• Nested navigation roots in the same Activity or Fragment.
• Side-by-side navigation roots in the same Activity or Fragment.
• Multiple simultaneously interactive Activities or Fragments, such as multi-resume mode.
• Pages or tabs that share one LifecycleOwner, such as Compose HorizontalPager pages or non-Fragment ViewPager2 pages.

Validation

The implementation is covered by unit tests, lifecycle integration tests, and sample app flows covering navigation root handoffs, transaction restoration, dialogs, Fragment replacement, and ViewPager pages.

Follow-up

Update the Android Navigation documentation to describe the supported multi-root lifecycle scenarios and current limitations.

References

• PR stack: #6301, #6302, #6304, #6305, #6307, #6309