Allow deferring commit of a same-origin cross-document navigation

[noamr]

What problem are you trying to solve?

When switching between pages, the old page might want to customize the navigation experience, e.g. by displaying an exit animation or asynchronously preparing a view-transition.

What solutions exist today?

The developer can intercept the navigation (e.g. navigateEvent.intercept({precommitHandler}), and start a new navigation when they're ready.

However, this would create a slow end result as the cross-document navigation initiation is delayed.

How would you solve it?

There are two options as to how to resolve this:

1. A generic pageSwapEvent.waitUntil(promise), allowing the developer to defer commit as much as they want.
2. Provide some heuristics to particularly allow some animations to run until finish before committing.

Anything else?

This is different from #10997, where the "unload" actions are also valid for cross-origin navigations (e.g. an IndexedDB transaction). This is specific for in-app (same-origin) navigation customization.

cc @jakearchibald

[nickcoury]

Are there any signals available that would indicate when the next page is ready? Use cases that are coming to mind:

1. Showing infinite skeleton loaders until the next page is ready. This is kind of possible today by just playing an animation on the outgoing page, but the animation will freeze when the document is unloaded and before the next page is ready which is visually jarring. If this proposal is implemented in a way that the animation plays until the next page is ready to transition (using render blocking + cross-doc VTs) then that would allow an instant visual response to the navigation click and also a seamless transition.

2. "Catching" an animation in-flight. Imagine the outgoing page plays a 350ms animation but the new page is ready in 50ms. If this can be detected, it would be ideal for the site to resolve the promise and swap to an animation that includes the new page content faster, similar to native mobile apps rendering skeleton loaders that are replaced with new content during a transition. Though this already feels a bit challenging to coordinate writing down the idea. I wonder if there's a different cross-doc VT mode that could be played on the exiting document but using the new page as the live root pseudo. This would also need more thought if the new root pseudo starts as skeleton loaders but is replaced dynamically with the new page content. Perhaps it could utilize render blocking and a convention that the new content overlays any other content in the new pseudo upon render.

The main benefits of the heuristic approach would be simplicity, and the potential for the browser to optimize certain cases like cached content to avoid unnecessary latency.

This might benefit from some kind of timeout as a safeguard. I don't think there's a vulnerability for same-origin given the user could always intercept and stop the navigation, though there might be if this was cross-origin. A timeout could prevent a footgun if the website doesn't properly resolve the promise.

[noamr]

@nickcoury agreed, there are some advantages to keeping this as an animation-based heuristic:

• it's easier to reason about letting the browser abort and force the commit
• it's more difficult to abuse
• A new API for work during unload #10997 already deals with non-UI use-cases, which are usually not limited to same-origin navigations
• it's easier to connect with browser heuristics that have to do with the next page, e.g. waiting for render-blocking resources if the next page is prerenedered.

[jakearchibald]

Is it possible for navigation comiting to be aborted/cancelled after pageswap fires?

[noamr]

Is it possible for navigation comiting to be aborted/cancelled after pageswap fires?

Not at the moment.

[jakearchibald]

I guess there can be an AbortSignal if that ever happens

[noamr]

If we do want to go with the explicit/generic/non-heurisic route, perhaps a direction would be to better align this with prerendering.

Something along the line of this:

// Initializes prerendering if that hasn't started yet, and returns a promise that resolves when all the render-blocking resources of the new document are loaded
navigateEvent.prerender();

// This doesn't intercept, but allows deferring the commit without waiting for `pageswap` to do so.
navigateEvent.defer(promise);

// Then you can do something like:
navigateEvent.defer(Promise.race([
  navigateEvent.prerender(),
  new Promise(resolve => setTimeout(resolve, 1000),
  document.startViewTransition(() => preview_transition()).finished
]);

I still think there is value in making this declarative and giving the browser a bit more control; But perhaps both options are viable.

[noamr]

cc @nt1m @emilio @zcorpan
Would love to hear your thoughts about whether this would work better as a lower level enabler or as an animation-based heuristic.