feat: frame-perfect and state-backed durable SPA scroll restoration

[jordanw66]

Overview

Update: Included the durable scroll history changes because they required changes to scroll restoration API. The next PR to address SPA context recovery should be a transparent upgrade (no API changes) that can be merged post-release if it's not done/agreed upon before next week.

As mentioned here (#3244 (comment)), this PR correctly implements the following:

• Properly disables the built-in browser scroll restoration when SPA is enabled.
  • It needs to be disabled during SPA, otherwise you will get pre-scrolling.
• Makes the manual scroll restoration synchronous with render.
  • Async has problems with potential for draws between render and when the event loop gets around to the scroll restore.
  • Simple, implemented in the same way alongside the View Transition.
• Makes the scroll history durable by storing it directly in history state instead of session storage.
  • This is a must to eventually recover scroll states on resuming sessions (desktop, mobile). Browsers natively recover MPA scroll sessions by storing scroll positions in the tab history. With session storage, it becomes impossible to replicate MPA.
  • Mobile browsers specifically can lose session storage very easily resulting in the loss of all scroll history.
  • Because state cannot be updated after a pop, it requires a scroll handler to be added when upgrading to SPA, but we are very careful to debounce reasonably here. Performance impact should be negligible.

The navigation API shipped live in Chromium 102+, in a future PR I can implement this to simplify SPA navigation/scroll in browsers that support it and leave the state-backed SPA as a fallback.

Note: This PR does not address these issues:

• Complete loss of SPA ctx on refresh and bfcache clear.
• Complete loss of scroll restore when losing SPA as above.

These will be addressed in a follow-up PR to make SPA navigation recoverable and function nearly identically to MPA in all circumstances, you should not be able to tell the difference.

What is it?

• Feature / enhancement
• Bug
• Docs / tests / types / typos

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.

Use cases and why

• 1. One use case
• 2. Another use case

Checklist:

• My code follows the developer guidelines of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• Added new tests to cover the fix / functionality

[stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[manucorporat]

Impressed with the PR! good job, i will love to merge this before the next big release (next week!)

[jordanw66]

@manucorporat I fixed the lint issue, not sure how I missed that.

[jordanw66]

@manucorporat I've added changes to this PR to move scroll history directly into state instead of session storage, I've added an explanation for why this is needed above. In short, it's required to mimic browser native scroll restore when restoring sessions on desktop/mobile. Mobile browsers specifically can lose the session storage/scroll history very easily. (I don't think there is any other way to easily do this)

The reason I included it with this PR, is because it makes changes to the scroll restore API surface, better now than later.

The next PR to resolve SPA context recovery will make no breaking API changes.

Please let me know if the solution proposed in this PR is acceptable to you, a lot of care has gone into making sure it is implemented correctly with little or no overhead. If not, we can revert to the original PR.

[jordanw66]

Apologies, unit tests worked locally because project was built first, I decoupled clientNavigate from Qwik, everything should pass now cc @manucorporat

[manucorporat]

This is amazing, planning to do some extra manual testing before release. I am not sure i am a big fan of the restoreScroll logic in core (refering to the logic added around view transitions), is it unavoidable?

[jordanw66]

@manucorporat I think it is unavoidable because the only way to make sure scroll happens without jumping/flashing is to make it synchronous with render. The only callsite for this is right there after render in core. The moment you introduce promises you push it somewhere else in the event loop and create potential for gaps where draw will happen.

This is why I kept it very minimal in core, only a check and run.

This hook can also benefit other third-party frameworks in the future, without this hook after render there is no way for them to restore scroll synchronously either.