Revise two-phase transition explainer

Updated the two-phase transition explainer to enhance clarity and detail on cross-document navigation and proposed solutions.

Author: noamr

css-view-transitions-2/two-phase-transition-explainer.md

@@ -1,54 +1,92 @@
-# Two-phase view transition
-Making cross-document view-transitions feel instant and seamless.
+# Two-phase cross-document navigation
+Making the navigation experience customizable & declarative.
 
-See whatwg/html#10616
+See whatwg/html#10616, whatwg/html#11819 and w3c/csswg-drafts#12829.
 
-# Current state
-View-transitions don’t start immediately - rendering is paused until the new state is ready. 
-This is especially visible in cross-document view transitions, where the transition only captures the old when the new document’s response arrives, and starts when the new document is ready to render.
+# Overview
+The period between initiating a navigation (e.g. clicking a link) and consuming the content of the next page ([FCP](https://web.dev/articles/fcp)), is a sensitive moment in user experince.
+It is a point in time where users are very likely to notice delays, jarring moments of frozen display, and abrupt changes to presentation.
 
-This can create a jarring or abrupt experience.
+The core of this being difficult stems from a tradeoff between speed and smoothness.
+The new document becomes activate ASAP (in favor of speed), at the moment the headers are received.
+However, it cannot render until all of its render-blocking resources and elements are present (in favor of smoothness, preventing FoUCs).
 
-# Current workarounds
+This "uncanny valley" where the old page is no longer active but the new page cannot render anything is far from being an optimal user experience, and the knobs given for developers to control it are crude and implicit.
+
+# Current knobs
+
+## Cross-document view transitions
+
+This feature declaratively makes the navigation smoother. However, the view-transition starts very late. It captures the old state when the new page's response headers arrive, and then freezes the presentation until rendering is unblocked.
 
 ## Starting an animation manually on the old page
-This is possible, however the old page cannot delay the navigation, which means the animation is likely to be interrupted when the navigation commits.
+This would create an instant response to the navigation, however the animation would be interrupted as soon as the new page's headers arrive, freezing at that point. So by default this would be both abrupt and jarring.
 
 ## Intercepting the navigation and restarting it when the animation ends
-This works but is hard to achieve without slowing down the whole navigation process.
+This would feel smoother but slows down the whole navigation and tweaking it correctly is finicky.
 
 ## Timing out render-blocking
-This can reduce the “frozen” time, however it means the transition doesn’t end at the optimal state, and also doesn’t help with making it feel instant.
+This can reduce the jarring time, however it means the transition doesn’t end at the optimal state, and also doesn’t help with making it feel instant.
 
-# Proposed solution
-The core of the problem is that view-transitions require a start and an end phase before starting, but we don’t know the end phase in advance when it is computed in an async function (e.g. in a navigation).
+# Two-phase transition
 
-## In a nutshell
-Proposing to prototype a “two-phase” view-transition: 
-Instantly start a transition to a state that can be computed quickly enough or synchronously. Call this a “preview” state.
-When the to-preview transition ends, transition from there to the final state.
-Only interrupt the first transition after a timeout, otherwise stall the navigation commit until finished.
-This should ideally not delay the LCP / loading experience of the new page, as the content keeps loading (and potentially prerendering) in the background.
+To make this part of the experience feel more seamless, developers should be able to create a "two-phase page transition".
+This transition starts *instantly* after navigation initiation (link click), and continues *smoothly* until the next page is ready to render.
+The instant part of the transition can only use information knows to the old page, which could be a skeleton of the new page or something generic of sorts.
 
-## Phase 1: script-invoked preview
-We can create this kind of seamless/instant experience without any new CSS, and potentially without needing to fully spec it normatively by changing the behavior as follows:
-Calling document.startViewTransition while there is an uncommitted navigation currently works, however it might get cancelled if the navigation is committed.
-Instead, if setting up that preview transition’s new state is fast enough so that it is activated before commit, let the animation run its course and use the final state as the “old” state for the cross-document view-transition.
+To achieve that, there are 3(?) potential avenues
 
-## Phase 2: declarative, using route-matching
-Instead of relying on carefully crafted scripts, use the proposed [declarative routing feature](https://github.com/WICG/declarative-partial-updates/blob/main/route-matching-explainer.md), and compute the preview value declaratively and synchronously by applying the style associated with the new route and using it as the intermediate state.
+## Heuristic-based
+Allow a subset of animations, e.g. ones that started after the navigation was initiated, to continue until the new page is ready to commit.
+This would allow instant reactions to a navigation while not creating the abrupt experience of spotting it prematurely.
 
-Something like this, though perhaps the “preview” opt-in is not necessary and we can make this inferred
+## Low-level knobs with prerendering support
+Currently, deferring the commit, even for same-origin navigation, is not possible. So the browser is responsible for the handover,
+not allowing the developer to curate this experience.
 
-@route (to: article) {
-  .article-skeleton { display: block } 
-}
+### Deferring commit
+Something like `navigateEvent.waitUntil(promise)` (or `defer` or some such) can let the developer tweak the handover point.
+This can of course also be a footgun as it's a simple way to delay navigations, however it's arguably less of a footgun than the current workarounds.
+
+### Responding to prerender
+When prerendering takes place, a more sensible time to hand over the control to the new document is when it is ready to produce a frame (all the render-blocking resources had been discovered).
+However, it is not guaranteed that the destination page is prerendered, and there is no hook to know when the new page is ready to render.
+
+A rather low level way to expose this is `navigateEvent.prerender()` which initiates a prerender if that hasn't happened yet, and returns a promise that resolves at that point, and compose it with the `waitUntil` method above.
+It is also possible to short-circuit this and somehow declare "please defer commit until prerender", which is perhaps safer than a general-purpose promise-based API.
+
+## Declarative preview transitions
 
+The above knobs might be very effective, but might also require expertise to get right.
+
+```css
 @view-transition {
   navigation: preview;
+  types: skeleton;
+}
+
+:active-view-transition-types(skeleton) {
+/* style the transition here */
 }
+```
+
+This is especially expressive together with route-matching:
 
-The big advantage of doing this declaratively is that the author doesn't have to worry about "cleaning up after themselves", e.g. in the case of restoring from BFCache.
-Since routing is declarative, the style of the "new" route would simply not apply when restoring the "old" page from BFCache because the user is no longer navigating to it.
+```css
+@route (from: movie-list) and (to: movie-details) {
+  @view-transition {
+    navigation: preview;
+    types: skeleton;
+  }
+}
+
+@route (movie-details) {
+  :active-view-transition-types(skeleton) {
+    /* style the page as a details page skeleton even if we don't have all the data */
+  }
+}
+```
 
+# Conclusion
+Proposing to pursue both the declarative and JS-based approach for completeness (one for ease of use, one for fine-tuning and complete control), and avoid the heuristic approach as it's a bit opaque and implicit.