feat(auth): onUpgradeFailure callback when account linking fails

[russellwheatley]

• Adds an onUpgradeFailure callback for anonymous user auto-upgrade failures.
• Allows apps to handle account-linking conflicts and suppress the default FirebaseUI error by returning "handled".
• Preserves anonymous user upgrade state correctly across provider redirect flows.
• Adds tests for credential, provider, failure-handling, and redirect upgrade behavior.

closes #1354

Below demonstrates onUpgradeFailure firing when auto upgrade anonymous user fails and also returns "handled" so error message does not appear in the UI.

Screen.Recording.2026-05-07.at.16.47.44.mov

[gemini-code-assist]

Code Review

This pull request introduces an onUpgradeFailure callback to the anonymous upgrade behaviors, allowing for custom error handling and suppression during the linking process. The changes include new type definitions, a centralized error handling utility, and updated logic for both credential and provider linking handlers. A critical issue was identified in the provider linking implementation where the unconditional removal of the user ID from local storage in a finally block would disrupt the redirect flow.

[russellwheatley]

I think I'd like to get some integration tests setup for this before going further with this PR as there are some changes to core behaviour.