fix: Wrap navigation proxy using requestAnimationFrame

[Cal-L]

Description

The change wraps both navigate and reset methods from navigation with requestAnimationFrame to ensure that it respects React's render cycles. This ensures that the navigation ref is being invoked with the latest context, which fixes race conditions associated with the navigation system not responding.

Changelog

CHANGELOG entry:

Related issues

Fixes: #25240

Manual testing steps

Expected behavior

• Immediate lock and biometrics should be enabled
• Navigate to any screen
• Background and foreground app
• Get prompted biometrics and fail it
• Navigates to the login screen

Screenshots/Recordings

Before

fail.mp4

After

fix.mp4

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

---

Note

Medium Risk
Changes how NavigationService.navigation behaves by returning a Proxy that defers navigate/reset, which can affect timing/order of navigation actions and introduces reliance on requestAnimationFrame. Tests were expanded to cover deferred vs pass-through behavior, reducing regressions but still touching app-wide navigation flow.

Overview
NavigationService now wraps the provided navigation ref in a Proxy that defers navigate and reset calls to the next frame via requestAnimationFrame, aiming to avoid React render-cycle timing issues.

Adds resetForTesting() to clear the stored navigation ref, and expands the unit tests to validate deferred behavior for navigate/reset plus pass-through/binding for other methods and properties.

^{Written by Cursor Bugbot for commit f3eecc8. This will update automatically on new commits. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[cursor]

Cursor Bugbot has reviewed your changes and found 4 potential issues.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeAccounts, SmokeConfirmationsRedesigned, SmokeIdentity, SmokeNetworkAbstractions, SmokeNetworkExpansion, SmokeTrade, SmokeWalletPlatform, SmokeCard, SmokeRewards, SmokePerps, SmokeRamps, SmokePredictions, FlaskBuildTests
• Selected Performance tags: @PerformanceLaunch, @PerformanceLogin, @PerformanceOnboarding
• Risk Level: high
• AI Confidence: 90%

click to see 🤖 AI reasoning details

E2E Test Selection:
This PR modifies the core NavigationService, which is a critical infrastructure component used throughout the entire MetaMask Mobile app. The change introduces a significant behavioral modification: wrapping navigate and reset methods with requestAnimationFrame to defer navigation calls to the next frame.

Impact Analysis:
The NavigationService is imported and used by 30+ files across the codebase, including:

• Authentication (app/core/Authentication/Authentication.ts) - Uses navigation.reset() for login/logout flows, vault recovery
• EngineService (app/core/EngineService/EngineService.ts) - Uses navigation.reset() for vault recovery during startup
• Redux Sagas (app/store/sagas/index.ts) - Uses both navigate and reset for state-driven navigation
• SDKConnect/SDKConnectV2 - dApp connection flows
• WalletConnect - dApp connection flows
• Deeplink handlers - handlePerpsUrl, handlePredictUrl, handleSwapUrl, handleBrowserUrl, handleRampUrl, handleDepositUrl, handleHomeUrl, handleTrendingUrl, handleApproveUrl
• Network Selection (useNetworkSelection hook) - Network switching modals
• Perps components - PerpsRedirect, PerpsTutorialCarousel
• Ramps components - handleDepositUrl, handleRampUrl, handleRedirection

Why this is high risk:

1. The requestAnimationFrame deferral changes the timing of ALL navigation calls throughout the app
2. This could affect race conditions, navigation state consistency, and user experience
3. Critical flows like authentication, vault recovery, and deeplink handling depend on this service
4. The change affects both navigate (50+ usages found) and reset (used in critical auth/engine flows)

Recommended testing:
All E2E test tags should run to verify that navigation works correctly across all major user flows, including accounts, confirmations, identity sync, network management, trading, wallet platform features, card, rewards, perps, ramps, predictions, and Snaps functionality.

Performance Test Selection:
The NavigationService change introduces requestAnimationFrame deferral for navigate and reset methods, which directly affects navigation timing. This could impact: 1) App launch performance - EngineService uses navigation.reset() during startup/vault recovery, 2) Login performance - Authentication uses navigation.reset() for login/logout flows, 3) Onboarding performance - Navigation timing during initial setup. The deferral adds a frame delay to all navigation calls, which could affect perceived responsiveness during critical user flows like app startup, login, and onboarding.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud