[Stack v5] Provide a consistent transition-event contract for navigation integrations

[ykai55]

Context

Following the discussion in lynx-screens#165, the maintainers clarified that Stack v5’s appearance callbacks intentionally follow platform-specific lifecycle behavior.

On Android, onDidDisappear can fire before the exit animation finishes. Backgrounding and foregrounding can also produce appearance events without a navigation change.

Integration concern

Navigation libraries need reliable signals for when a transition starts, completes, or is cancelled.

The RNS v5 integration in React Navigation PR #13115 currently maps appearance callbacks to transitionStart / transitionEnd. In the related discussion, @satya164 highlighted that normalizing these events in JavaScript requires substantial bookkeeping, coordination between screens, and fragile assumptions about lifecycle and AppState ordering.

Our concrete use case is closing a native host container after a screen’s exit animation finishes. An early completion signal cuts the animation short. onDismiss addresses completed removals, but does not provide a general contract for all transitions, including screen entry.

Proposal / question

Could Screens expose a consistent set of navigation transition events that:

• Report actual transition start, completion, and cancellation.
• Distinguish navigation transitions from ordinary app backgrounding/foregrounding.
• Define completion behavior for non-animated and interrupted transitions.

Platform-specific animations and lifecycle behavior can retain their differences. At least for transitions, navigation libraries should not need to understand Fragment lifecycle ordering or the corresponding iOS implementation details.

Would the RNS team consider providing this contract, either through dedicated events or another supported integration API?

cc @satya164 @t0maboro

[t0maboro]

Hi! We've decided to introduce separate events with transitionStart/transitionEnd semantics.

We’d like onDidDisappear to remain consistent with the native lifecycle behavior. Since ON_STOP on Android doesn't wait for the exit animation to finish, we can't guarantee any stronger timing guarantees for onDidDisappear beyond ensuring that it fires after onWillDisappear.

We're currently working on animation support, so I'll prepare a follow-up PR on top of this one to add support for the transitionStart/transitionEnd events.