[View Transitions] Extend render-blocking to support Document

[khushalsagar]

render-blocking allows the author to specify which resources are important for a good first paint. This allows the browser to defer a Document's first paint (new load only) up till a timeout.

It currently supports a limited set of resources that allow the blocking attribute. Two common use-cases which are missing are:

• Images. Documents frequently have a hero image. While a network delay here could be too slow, fetching them from the disk cache could be worth the delay.
• Document itself. Authors have no way of saying whether the "above the fold" content has been parsed and fetched.

It would be good to extend this concept to cover the above use-cases. Likely with a generic promise based API like:

document.renderBlockUntil(loadBlockingResources);

The downside of a promise based API is that the browser has no visibility into which resources are render-blocking, to prioritize fetching them. But it provides a lot of flexibility, and would work well if other APIs can already be used to prioritize network work.

This API would also be an important building block for View Transitions.

@noamr @xiaochengh @yoavweiss @nickcoury

[nickcoury]

I was just prototyping a version of this yesterday with a pair of style tags:

<style>
.render-blocked {
  display: none;
}
</style>
<!-- Above the fold content -->
<style>
.render-blocked {
  display: block;
}

There are several uses I see for this:

1. Avoid flashes of partially rendered content.
2. Lower the difficulty of getting frame-perfect transitions especially with more complicated DOM manipulations and async code paths. (VT API can also fulfill this if appropriate)
3. Possible performance gains from reducing layout thrashing.

JS API

I don't have a strong sense of an ergonomic JS API yet, but the promise one seems reasonable and would be flexible. The other method would be to have an explicit start() and stop() method, though the advantage of this is multiple pieces of code could independently render-block, and one wouldn't accidentally unblock the other.

A timeout could be a convenient parameter. It could be manually built into the promise API, though that's subject to a setTimeout not being blocked on the main thread.

On point 2 above, we frequently have cases where we remove old DOM, run some cleanup code, render new DOM, hydrate controllers that may further change DOM on instantiation, then finally have the final state ready. Given a lot of code is built to be async and non-blocking by releasing control back to the main thread, or uses requestAnimationFrame for certain use cases, we sometimes see 1 frame flashes of intermediate state before the final render. This is jarring to users and takes tedious coordination of client and framework code to prevent. This would bypass all of that and allow better structured code to focus on behaviors rather than rendering quirks.

One example we hit is fetching content from an async cache. Our transition service is separate from our fetching and rendering services. The transition code is responsible for cleaning up the previous content and removing old DOM, but the fetching + rendering holds the implementation details for getting and rendering new content. If the fetch service gets the content from a local async cache, the timing is such that we can show a blank page briefly before the renderer gets the content. We had to add complexity to coordinate this, rather than the transition service blocking rendering, removing old code, sending the request to fetch and render, then unblocking once the renderer is finished.

One consideration that comes to mind from some VT API use case is if animations or videos are allowed to continue to run during render blocking. In the previous example, the transition service might play a partial fade out animation on the old content to show the user the page is changing, not knowing if the fetch service will make a network request or hit local cache. Though I'm not sure if the complexity required for this is worth it.

HTML API

I can see the role of an HTML API, especially if this is used on an initial page render where JS will have less knowledge of the streaming page as it is parsed than the browser will. It might look something like this.

<meta rb-id="unblock" rb-timeout="500">
<!-- Above the fold content -->
<div id="unblock"></div>

I'm less certain this would be useful after the initial streaming load, as usually HTML inserted later on can be batched instead of streamed.

[khushalsagar]

It sounds like the use-case for a JS API is primarily for same-document navigations where removing the old DOM and populating the new DOM can't be an atomic operation. Does the HTML API suffice when loading a new Document? We're erring towards a declarative solution since it works better with browser optimizations like preload scanning.

One consideration that comes to mind from some VT API use case is if animations or videos are allowed to continue to run during render blocking.

This is fairly hard. Render blocking works by pausing frame production completely (as if the tab was backgrounded) so no animations or video playback can run. As an internal detail, we can keep accelerated animations running while you're mutating the DOM. But it becomes very difficult to reason about if the DOM mutation removes some element and its associated animation keeps running.

If you're ok with the page being static then you can kinda get what you want by hacking the VT API just for the render-blocking part. Something like:

document.documentElement.style.viewTransitionName = "none";
document.startViewTransition(asyncDOMUpdate);

We had to add complexity to coordinate this, rather than the transition service blocking rendering, removing old code, sending the request to fetch and render, then unblocking once the renderer is finished.

The transition service can use the code above to block rendering in the sequence you mentioned. This seems ok if the async part is hitting a local cache. If the fetch needs to hit the network, you probably still want to do that before suppressing rendering to keep the current page animating and interactive while waiting on the network.

[nickcoury]

Yes, that's the primary use case for the JS API for us, and the VT API would likely work well enough as long as it's still performant on a window of a frame or two.

[khushalsagar]

As spec'd, startViewTransition will do the following:

1. Render one frame and snapshot it. If no element has a view-transition-name, snapshotting has no cost. Chrome's current implementation might have a one frame delay here (we wait for this frame to progress until a point before realizing no element needs a snapshot) which we can optimize.
2. Dispatch the callback passed to that function. Now its up to the author how long this takes.
3. When the callback is done (or timeout happens), start rendering again.

There shouldn't be any performance issues even if the callback takes one or 2 frame's worth of latency. Let us know if you're not seeing that in practice.

[noamr]

I wonder if for the view transitions case this can be a CSS property rather than an HTML property, e.g. putting
view-transition-capture: stall or so on elements that are not yet "settled", giving a hint to the UA that the new state is not ready to be captured. This means though that we keep have to be calculate style even if we end up not performing layout/paint.

[khushalsagar]

An explainer clarifying the use-case and a concrete proposal is now available here.

[nickcoury]

One question on the proposal is if requiring JavaScript to unblock rendering will be a performance bottleneck relative to a more declarative solution? My understanding is that the context switch to JS land can be expensive especially on initial page load when a lot of things are going on. Or is that just as performant as an HTML or CSS directive to unblock?

[eeeps]

For the partial rendering case, this proposal expects authors to:

1. know the layout (true most of the time)
2. know the "settled" DOM content (not true in many dynamic/interactive contexts)
3. make a judgement call about a "worst-case scenario" - the most content that will generally be rendered above the fold, given the known layout and current device/software landscape, and common user preference settings. (this is really hard, see also, the frequency of above-the-fold <img loading=lazy>)

That's a lot to ask, and I worry that poor usage of this API (because of the difficulty and in many cases impossibility of using it well) will lead to worse experiences for users (very slow LCPs).

[khushalsagar]

One question on the proposal is if requiring JavaScript to unblock rendering will be a performance bottleneck relative to a more declarative solution? My understanding is that the context switch to JS land can be expensive especially on initial page load when a lot of things are going on. Or is that just as performant as an HTML or CSS directive to unblock?

I don't think the script switch should be a problem. If an author is explicitly unblocking rendering before full Document parsing, that's a strong hint that this is a good spot for the parser to yield for rendering. So a content switch away from the parser will likely be done anyway.

That said, a declarative solution like a new tag: <unblock render> is also doable. The script way is preferred just for consistency, since that's how authors are supposed to preemptively unblock rendering on other resources (script, stylesheets). @mfreed7 @chrishtr in case they have an opinion on whether a declarative tag is worth any perf implications.

That's a lot to ask, and I worry that poor usage of this API

The targeted use-case for partial rendering is View Transitions. The author knows exactly which DOM nodes need to animate (will have a view-transition-name) for each transition. So they can unblock rendering when the last required node for a transition has been parsed.

[noamr]

For the partial rendering case, this proposal expects authors to:

1. know the layout (true most of the time)

2. know the "settled" DOM content (not true in many dynamic/interactive contexts)

3. make a judgement call about a "worst-case scenario" - the most content that will generally be rendered above the fold, given the known layout and current device/software landscape, and common user preference settings. (this is really hard, see also, the frequency of above-the-fold <img loading=lazy>)

That's a lot to ask, and I worry that poor usage of this API (because of the difficulty and in many cases impossibility of using it well) will lead to worse experiences for users (very slow LCPs).

People can do this today eg by starting with body at display:none and changing to display:block once enough content had been parsed.

In addition, LCP is not the only relevant metric here - there is also CLS.

Blocking render until enough is parsed to avoid jumpiness is a legit trade off that developers should be able to make use of. Sometimes the way to avoid the footguns is with education rather than by limiting the choices.

[khushalsagar]

People can do this today eg by starting with body at display:none and changing to display:block once enough content had been parsed.

Adding some anecdotal data for this, Chrome has a feature called paint holding which will defer displaying a web page until it has FCP content. We've heard from authors using display: none or opacity: 0 on html/body element on top of that to effectively get the behaviour proposed here.

The author knows exactly which DOM nodes need to animate (will have a view-transition-name) for each transition.

Adding a concrete use-case from a real world site. Say you have a header or footer which is position: fixed so its guaranteed to be displayed in viewport irrespective of the device. And you want it to slide in from viewport edge (or stay at the same spot if it was in the old Document as well). The only way to get the transition right is for the browser to parse those elements before first render. Otherwise incorrect animations will be set up as described here.