This is an incomplete, extremely early draft and work in progress. You have been warned!
This specification defines a set of directives that can be used by authors in order to opt-out of the user-agents' slow path and apply self-imposed interventions on their sites, in order to make sure that they are as fast as they can be, and that the user experience is not harmed by either first or third party content. User agents will modify their behavior in order to enforce these directives, and ignore "slow path" instructions by the sites. Applications that embed Web pages and link to them can use these directives as guarantees pointing to the lack of performance and UX anti-patterns in those sites, and potentially increase their ranking or exposure to users as a result. Content blockers may use those guarantees in order to make their decision whether to block a certain resource or not in an automatic manner.
This is a work in progress and may change without any notices.
Implementers SHOULD be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage SHOULD join the mailing lists below and take part in the discussions.
With the increasing importance of mobile, Web site performance and pleasant mobile user experience are becoming ever more critical. Yet the increasing complexity of today's Web application means that simply adhering to performance best practices only gets Web authors so far, as they have hard time dictating and controlling the performance of third party components in their pages, as well as components built by other teams in their organizations.
Furthermore, the increasing use of content aggregators increases the need for performance and user experience guarantees. Embedding applications (e.g. search engines and social networks) are reluctant to send users towards links that contain slow content with poor UX, as that reflects negatively on them and the perception of their applications.
As a result, there's an increasing need for guaranteed performance, where the embedders can know for certain that mobile performance anti-patterns were avoided by the site to which it links.
At the same time, and probably for similar reasons, usage of content blockers have seen a dramatic rise, as users are more performance and bandwidth conscious, and are willing to install browser extensions and applications to help them increase performance, reduce bandwidth consumption and improve overall user experience.
Therefore, there's an increasing need for a mechanism that would give authors control over their sites, and give them the opportunity to opt-out of various features of the Web platform that are inherently slow or from behaviors that are known to irritate users and result in bad mobile user experience. These same mechanisms can be used for guarantees for content embedders as well as content blockers, and enable them to make smart descisions based on the known performance characteristics of the content.
This specification will define a set of directives that will provide authors the required level of control over their site's performance, and will provide performance guarantees of the site to interested parties.
The mechanism defined here borrows heavily from the syntax of Content-Security-Policy[[!CSP3]], including its reporting capabilities. The main difference is the defined directives.
The directives defined can be divided into three groups: directives enforcing performance best practices and opting into the fast path, directives aimed at reducing the consumption of resources, and directives aimed at enforcing mobile-friendly user experience.
Synchronous scripts and blocking external stylesheets add multiple RTTs to the time it takes to render the page and present the user with something useful. Guaranteeing their absence verifies that the critical rendering path is clear.
Web fonts are in many cases another critical blocking resource. Although layout and rendering are
possible even before the fonts are discovered and downloaded, by default many browsers will not show the text in their absence, for fear
of causing a FOUT (Flash Of Unstyled Text). On slow mobile networks, that can cause a significant delay in the time when the site is
actually useful for users. A directive can indicate that this is not the case, either because the site is not using Web fonts, or
because it is using techniques that render the fallback font first. (e.g. font-display: swap)
Scroll and click-hijacking are common techniques used for figuring out visiblity of elements, lazy loading and more. They also often result in laggy and janky experience, especially on mobile. The advent of Intersection Observer enables authors to tackle these use cases without hurting performance. Passive events enable authors to opt-in to having scroll and click events, without paying the associated performance price of synchronously waiting for the events to return to know if the default action was cancelled or not. A directive that would guaranty that all events are passive, effectively guarantees lack of scroll jank, which is extremely important on mobile.
Content shifts after resource downloads are a common anti-pattern on mobile, as it distracts the user and causes them to lose their reading location. They are typically caused by images or other intrinsic width resources that did not have a "reserved" place in markup/styles before that, so their intrinsic dimensions are used for layout, causing content to shift once those intrinsic dimensions are known. A directive can be used to guarantee that this is not the case.
Libraries like fastDOM are used to guarantee to authors that they are not performing consecutive reads and writes, forcing all reads and writes to be performed in a serial fashion.
Browsers can provide similar guarantees, which result in improved performance
Images on the page that are outside of the initial viewport can often be downloaded and delay the page's onload event without actually being seen by the user. That issue is significantly worse on mobile, where the viewports can be very long.
A lazy loading directive can be used to indicate the browser that images outside of the first few images are all lazy loaded.
The browser can then act on that directive and avoid loading those images.
Since there's no native lazy loading API today, we may need to add some related primitives to enable the loading of those images without changing the `src` attribute.
Scripts run in the context of the page and in some cases in the context of an iframe on the page, can "hog" the CPU and prevent other more critical scripts from properly running.
A throttling directive can instruct the browser to prevent such "hogging" and throttle down certain scripts that and iframes.
Today when a user clicks on a link, they have no means to know what would be the implications of that on their data plan and their bill. A directive committing a Web site not to surpass a certain amount of download data, and restricting its ability to download more can provide such guarantees to users.
Can we provide certain directives that would enable something like acceptable ads to be processed automatically and won't require a "certified" stamp? Will they be enforceable?
Does this cover all the annoying things sites do?
The intent of this specification is to provide control mechanisms that are very similar to those of Content-Security-Policy[[!CSP3]]. Authors should be able to apply directives to all hosts, certain hosts, and unlike CSP, to all except certain hosts. Similiarly to CSP, there would be a report-only mode that would enable authors to test their configuration. Unlike CSP, we may need to be able to specify "report" vs. "enforce" mode on a per directive basis.
Some directives may require additional values and parameters.Does this cover all barriers to adoption and enable developers to avoid breakage?
Add something here
Can we steal everything but the directive definitions from CSP?
There is only one class of product that can claim conformance to this specification: a user agent.
Add use cases
Register headers, etc
No impact, as this reveals nothing about the user. Web sites should be careful when declaring personalized policies.
Probably CSP