xiaochengh/proposal.md

## proposal.md

      
    Raw
  

              proposal.md
            
          
    (This version is obsolete. Please refer to the latest version)
Explainer

All current browsers already have a render-blocking mechanism: after navigation, the user agent will not render any pixel to the screen before all stylesheets and synchronous scripts in <head> are loaded and evaluated (or a UA-defined timeout is reached)¹. This prevents a Flash of Unstyled Contents (FOUC) and ensures critical scripts (like framework code) are executed, so that the page is usable after the first rendering cycle.
In this proposal, we extend the above idea and propose a new attribute blocking that can be added to <link> and <script> elements in <head>. For now, we would only allow one value blocking="render" to support the most demanding use cases, but we would also like to keep the syntax open for future extensions.
Use cases


Block rendering on a critical web font to prevent layout shifting or a flash of invisible/unstyled text (see here for more details). It also works in the preloading of critical resources of other types, like images, json, etc.

<link blocking="render" rel="preload" href="critical-font.woff2"
      as="font" type="font/woff2" crossorigin>

Block rendering on script-inserted stylesheets or scripts. This prevents a FOUC when, e.g., the page uses a loader script to load the actual business stylesheets:

<script>
let link = document.createElement('link');
link.rel = 'stylesheet';
link.href = 'business-style.css';
link.setAttribute('blocking', 'render');
document.head.appendChild(link);
</script>

Block rendering on an async script, so that the script doesn’t block parsing but is guaranteed to be evaluated before rendering starts. This is useful for, e.g., SPA loader and A/B test framework scripts, which can be loaded asynchronously but need control over what is displayed on the first render.

<script blocking="render" async src="async-script.js"></script>

Besides, while rendering is blocked, requestAnimationFrame() callbacks should not be fired². So we can add a requestAnimationFrame() in <head> to perform some tasks right before the first rendering cycle to, e.g., ensure a better-looking first paint:

<script>
requestAnimationFrame(() => {
  let status = getResourceLoadingStatus();
  putProgressBarOnPendingResources(status);
});
</script>
Technical Details

Prerequisites

This proposal is blocked on #3355.
In particular, this proposal requires the notion of “render-blocking resource”, so that after a navigation, the UA can finish loading all render-blocking resources first and then start rendering. This notion hasn’t been specified yet, but all browsers are treating external stylesheets as render-blocking resources (with subtle differences) to avoid a FOUC.
Before resolving the issue, this proposal assumes the following model:

After a navigation, the browsing context will first enter a “render-blocking period”, during which it has no rendering opportunities; it may have rendering opportunities only after the render-blocking period ends
During the period, before the parser inserts the <body> element, UA collects certain “render-blocking resources” from the document, adds them into a set of pending render-blocking resources, and fetches them
When a render-blocking resource finishes loading (either successfully or exceeds a UA-defined timeout), it is removed from the set of pending render-blocking resources

For scripts, they are removed after evaluation³ instead of loading finishes


The render-blocking period ends when both are satisfied:

Parser has inserted the <body> element
The set of pending render-blocking resources have become empty


Currently, all browsers treat external stylesheets and non-deferred scripts as render-blocking resources, so the above assumption seems reasonable.
The proposal

This proposal introduces a new attribute blocking on the <link> and <script> elements. The attribute value is a set of space-separated tokens, where the only allowed token is render, indicating that the resource is render-blocking. The user agent should ignore all tokens that are disallowed or unsupported.
Note: The syntax is designed for forward compatibility, as future extensions may add new tokens.
The attribute is effective only when all of the following requirements are satisfied:

The element is inserted into the document before the parser inserts the <body> element

When on a <link> element, the link type must be stylesheet or preload
When on a <script> element, the defer attribute must not be set


The other attributes together allow the UA to fetch the resource

For example, the element is not disabled, media query must match, ...
TODO: How exactly does it work? Expand this part.


Note: The attribute works for both parser-inserted and script-inserted elements as long as it’s inserted before parser inserts <body>. The implications include, for example, if an async script tries to insert a render-blocking stylesheet or script, since async scripts don’t block parser, the inserted element may or may not be actually render-blocking. This is due to the racy nature of async scripts, which this proposal has no intent to change.
Interactions with other specs


[HTML] In the update the rendering step, animation frame callbacks will not be run when rendering is blocked, because the document has no rendering opportunities.
[Priority Hints] If a resource is render-blocking, its importance will be overridden to high, so that rendering won’t be blocked on low-priority resources.

Possible extensions

This section includes ideas that we discussed but chose to not include in the minimum viable product for various reasons. They may be added into later versions.
Other operations to block/unblock on

Note: this part shares a lot of common ideas with the before-foo milestones in yoavweiss@’s proposal.
As mentioned before, the syntax of the attribute is intentionally left open for extensions. We may introduce a negation syntax, so that each resource can selectively block and unblock certain operations (or “milestones” as termed by Yoav’s proposal) in the page’s lifetime. For examples:

Async CSS:

<link blocking="!render !parse" rel="stylesheet" src="async-sheet.css">

A script so unimportant that we would like it not to block anything: not only parser and rendering, but even the document load event:

<script blocking="!render !parse !load" src="minor.js"></script>
The list of milestones to block or unblock may include:

render: the first rendering cycle
parse: parsing of subsequent DOM contents
documentcontentloaded: the DocumentContentLoaded event
load: the document load event

(We considered using blocking="none" to unblock everything. It does not seem to be a good idea due to forward-compatibility reasons.)
A side-product is that async/defer scripts may be easier to explain. Async script is equivalent to blocking="!parse", while defer script implies blocking="!parse documentcontentloaded" but still has some other implications.
We chose to propose render as the MVP because it has the most demanding use cases and keeps the initial proposal simple. With the other milestones, there are other complications that we need to consider. For example, the interaction between milestones, browser’s internal operations hooked to the load event, and etc.
Explicit timeout

We may want an additional attribute to set an explicit timeout for the blocking period, e.g., blockingtime="500ms". This overrides the UA-defined timeout, and makes the resource render-blocking for at most 500ms.
Pros:

This may be useful for certain images (like progressive JPEG), so that they can be rendered at a lower quality before fully loaded.
This gives developers control over the UX if the connection is slow. For example, if my webfont really is taking several seconds for a user with a slow connection, forcing them to stare at an unrendered page while the font downloads can be a really bad tradeoff. Having a timeout would solve this issue.
Power developers may know how complicated their client-side rendering is to fine tune that timeout. Maybe they can afford more leeway for network latency if their first frame renders quickly enough.

Cons:

A good timeout value depends on the connection speed, which varies user by user. Developers may not have a good strategy to set this timeout, which means this extension doesn’t make things better. The user agent is in a better position to understand these kinds of tradeoffs.

Alternative criteria to stop render-blocking

For certain types of resources, we may want it to block rendering first, but unblock as soon as certain parts of the resource are available. For example, if we want to eliminate layout shifting for an image, we can unblock rendering when the metadata (which includes dimensions of the image) is available, or when a certain proportion of a progressive JPEG is loaded.
Prevent 3rd-party abuse

As 3rd-party scripts can set element attributes in general, they may abuse this new feature by marking too many resources render-blocking, and harm the page load experience. To avoid that, we may introduce a JavaScript API that cancels any explicit render-blocking added to an element via the blocking attribute.
document.unblockRendering(element);
We may also provide APIs for how much render-blocking time each resource contributed, so that developers can identify ill-performing 3rd-party scripts more easily.
beforefirstrender event

Add a beforefirstrender event that fires after all render-blocking resources have finished loading, and before the first rendering lifecycle update.
It gives the developer a chance to deterministically control the first frame based on which non-critical resources were fetched or timed out, how much DOM parsing was finished etc. This hook may be used to abort or modify a transition. For example, if they'd rather show a loading screen UI instead.
The event is not included by the proposal, since it’s equivalent to the first requestAnimationFrame().
Further Reading

Eliminate layout shifting for critical web fonts

When the page has a critical web font served via a channel that is fast in most circumstances (e.g. a page using a font from Google Fonts), it is reasonable for developers to aim at a UX similar to locally installed fonts. In particular, both of the goals below should be achieved:

The page layout is stable. There should not be any flash of invisible text or layout shifting due to swapping from a local fallback font to the web font.
The web font should eventually be used to render the page.

However, all current solutions are either unreliable, hacky or cumbersome:

font-display: optional guarantees stable layout, but comes at the cost that the critical web font might not be used for rendering. If the web font doesn’t finish loading when needed, it will never be used and the page ends up in a fallback font.
Preloading an optional web font guarantees stable layout and makes the font more likely to be picked up by rendering, but still doesn’t guarantee the font being used.
Preload an optional web font and block rendering with other means/hacks, like using Javascript or adding an empty external stylesheet (as in crbug.com/1231827). This has a much higher chance to guarantee both objectives. However, it seems pretty bad to recommend hacks to web developers.
Adjust fallback font metrics with @font-face descriptors, so that the layout shift is minimized when swapping fonts. While achieving both goals, it’s not easy for web developers to adopt, as there are many adjustment parameters to figure out. It would be better rolled out by web font providers.

Both goals can be accomplished by preloading the web font with blocking="render".

Footnotes

[1] The exact behaviors differ slightly.

[2] Current browsers have different behaviors, and this proposal would like to standardize it. See test case.

[3] We only block rendering on the synchronous parts of the script. We don’t need to block on asynchronous code like event listeners, Promise.then() and etc. This implies that in the case of a module script with top-level awaits, we’ll block rendering only up to the first await, because await is equivalent to a Promise.then().