fix: handle router view transition rejections

[Mohamed Mansour (mohamedmansour)]

Why

A router-owned view transition can reject its animation ready promise even after the route DOM commit succeeds. Leaving that rejection unobserved produces an unhandled browser error for superseded or invalidated transitions.

Approach

Attach one shared rejection handler to transition.ready immediately after starting the transition. Keep updateCallbackDone as the only readiness barrier, preserving genuine commit errors and allowing rapid navigation without waiting for animations. The browser already marks finished handled; it only rejects alongside a failed commit callback.

Reuse the existing router unit tests and browser fixture, with no new dependencies, fixtures, configuration, global rejection suppression, or delayed resize. Update the specification and public routing contract. Measured bundle growth is 50 minified bytes (21 gzip bytes).

Validation

• Native Chromium 153 supersession and invalid snapshot state regressions fail before the fix with unhandled ready rejections (AbortError and InvalidStateError) and pass afterward.
• Router unit tests: 116 passed, including commit barrier timing and exact-identity callback error propagation.
• Router Playwright suite: 36 passed, 4 pre-existing skips. Transition regressions repeated 10 times: 30 passed.
• Strict E2E type-check passed.
• cargo xtask check: passed, including docs, in 149.5 seconds.

Reproduction limitation: Actual viewport resize immediately after route notification passes without page errors, but resize alone did not reproduce the reported abort in this small fixture/browser before the fix. Deterministic native supersession and invalid snapshot capture establish the rejecting promise and regression instead.

[mddinbox]

Thanks for the fix and the error-identity coverage! One non-blocking browser-compatibility follow-up: on Edge 153.0.4234.46 / Windows, a throwing route-component $destroy() still produces an unhandled rejection from transition.finished, even though the router catches and logs the original commit error. This reproduced through public router startup/navigation with real HTTP partial responses in 5/5 runs. It also occurs on the base branch, so this is not a regression introduced by this PR, and the successful-commit animation-skip fix remains valid.

Please consider observing both promises without awaiting them, keeping updateCallbackDone as the only awaited promise:

void transition.ready.catch(ignoreTransitionRejection);
void transition.finished.catch(ignoreTransitionRejection);
await transition.updateCallbackDone;

Here, ignoreTransitionRejection would be the renamed existing helper. Adding the finished observer removed the extra rejection in 5/5 runs while preserving the original router error log.

If included, please update the tests alongside the production change:

• Leave finished unhandled in the mock, using const finished = updateCallbackDone.then(() => {});, so the test verifies that the router itself observes the rejection.
• Narrow the source-inspection assertion to !source.includes('await transition.finished') rather than rejecting every transition.finished reference. Retain the behavioral test with pending ready/finished promises to ensure navigation does not wait for animation completion.

The combined runtime/mock/assertion adjustments passed all 86 tests in router.test.ts in an in-memory validation. A native-browser callback-failure test would additionally protect against specification-versus-browser differences, and the documentation’s automatic-handling assumption should be qualified.

A separate compatibility follow-up would also be reasonable given this PR’s scope.

[Mohamed Mansour (mohamedmansour)]

mddinbox Accepted in 30c8b6f9: both ready and finished are observed with the shared helper, while only updateCallbackDone is awaited to preserve the original commit error. I updated the mocks, assertion, and docs, retained pending-promise coverage, and added a native $destroy() regression that failed before the fix and passed 5/5 afterward; 116 unit tests, 38 browser tests (4 existing skips), strict typechecking, and the full quality gate passed.