From bc5484bdba32300c527bb00481cdda5cc0c788c1 Mon Sep 17 00:00:00 2001
From: Ehsan Karamad <ekaramad@chromium.org>
Date: Thu, 25 Apr 2019 09:06:29 -0400
Subject: [PATCH] Update and rename lazyload.md to
 loading-frame-default-eager.md (#293)

* Update and rename lazyload.md to loading-frame-default-eager.md

The policy is renamed accordingly.
---
 policies/lazyload.md                    | 47 --------------------
 policies/loading-frame-default-eager.md | 57 +++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 47 deletions(-)
 delete mode 100644 policies/lazyload.md
 create mode 100644 policies/loading-frame-default-eager.md

diff --git a/policies/lazyload.md b/policies/lazyload.md
deleted file mode 100644
index 91fc49a5..00000000
--- a/policies/lazyload.md
+++ /dev/null
@@ -1,47 +0,0 @@
-Lazyload Policy
-===========
-
-The `lazyload` policy-controlled feature can be used for a main frame or a nested
-`<iframe>` or `<img>` to overwrite the default or assigned value of the newly
-introduced `lazyload` [attribute](https://github.com/whatwg/html/pull/3752) for `<iframe>` and `<img>`.
-
-What does that mean?
-------------
-With the `lazyload` attribute, developers could prioritize the loading of different inline frames and
-images on a web page. This however could become a cumbersome process and not quite scalable for larger
-web sites specially given that applying the attribute is origin-agnostic. The lazyload policy aims to resolve
-this issue but changing a browser's decision on enforcing `lazyload` attribute for a browsing context and its nested
-contexts.
-
-Proposed Solution
-------------
-A new policy-control feature for lazyloading will alter lazyload behavior for a browsing context and its nested contexts. The feature will potentially modify the behavior of user agent towards the `lazyload` attributed value for nested resources. Essentially, when the feature is disabled for an origin, then no resources inside the origin can escape lazyloading by setting `lazyload="off"`. Specifically, if for a resource the `lazyload` attribute is set to:
-
-  * **`on`** then the browser should load the resource lazily.
-  * **`off`** then the browser ignores the attribute value and assumes **`auto`**.
-  * **`auto`**: there is no change in browser behavior.
-  
-This feature could be enforced either in the HTTP header or by using the `allow` attribute of an inline frame.
-
-Using the Feature
--------------
-
-This feature can be introduced with the HTTP headers. For instance,
-```HTTP
-Feature-Policy: lazyload 'self' https://example.com
-```
-would not allow synchronous loading for any `<iframe>` or `<img>` (that is not yet in the viewport) from origins other than `'self'` or `https://example.com`.
-
-Similarly, the feature could be set through the `allow` attribute of an inline frame:
-```HTML
-<iframe src="https://example.com" lazyload="off" allow="lazyload 'none'"></iframe>
-```
-which disregards `lazyload='off'` for all the origins including the `<iframe>`'s origin itself.
-
-The Extra Mile
------------
-In general the feature could allow an expanded set of enforcement policies with the use of [parametric features](https://github.com/WICG/feature-policy/issues/163). For instance, the feature could be used to enforce `lazyload` for certain origins (by enforcing `lazyload='on'` on all resources) and prefer synchronous loading for all local resources (i.e., suggest a default browser behavior of `lazyload='off'`):
-```
-Feature-Policy: lazyload 'self'(off) https://example.com(force)
-```
-In the example above an image in self such as ``` <img src="./foo.jpg"/>``` (which is same-origin) should be loaded synchronously, but, `<iframe src="https://example.com/page.html" lazyload="off"></iframe>` is loaded lazily due to policy enforcement.
diff --git a/policies/loading-frame-default-eager.md b/policies/loading-frame-default-eager.md
new file mode 100644
index 00000000..17df8a37
--- /dev/null
+++ b/policies/loading-frame-default-eager.md
@@ -0,0 +1,57 @@
+loading-frame-default-eager Policy
+===========
+
+The `loading-frame-default-eager` policy-controlled feature can be used for a main frame or a nested
+`<iframe>` to override the default behavior of the newly
+introduced `loading` [attribute](https://github.com/whatwg/html/pull/3752).
+
+What does that mean?
+------------
+With the `loading-frame-default-eager` attribute, developers could prioritize the loading of different inline frames on a web page. This however could become a cumbersome process and not quite scalable for larger
+web sites; specially given that applying the attribute is origin-agnostic. The proposed policy aims to resolve
+this issue by changing a browser's default decision for `loading` behavior.
+
+Proposed Solution
+------------
+The `loading` attribute can take one of the three values:
+  * **`eager`** indicating that the resource should load eagerly (i.e., load even when below the fold).
+  * **`auto`** the browser makes the call for the loading behavior; it probably defaults to `eager`.
+  * **`lazy`**: the resource loads lazily.
+
+The proposed `loading-frame-default-eager` policy will affect the `auto` attribute value in that when disabled, `loading="auto"` (or unset) will be treated as `lazy`, which means that frames with unspecified `loading` attribute will be lazily loaded.
+  
+This feature could be enforced either in the HTTP header or in the `allow` attribute of an inline frame.
+
+Using the Feature
+-------------
+
+This feature can be introduced with the HTTP headers. For instance,
+```HTTP
+Feature-Policy: loading-frame-default-eager 'none'
+```
+would cause all the nested `<iframe>`'s and the corresponding nested and auxiliary browsing contexts to load lazily, unless they have specifically set `loading="eager"`. For example, if the document has
+```HTML
+<iframe id="frame"></iframe>
+<iframe id="fast" loading="eager"></iframe>
+```
+then the `<iframe>` with `id="frame"` loads lazily but the `<iframe>` with `id="fast"` would load normally (eagerly).
+
+Similarly, to allow certain origins,
+```HTTP
+Feature-Policy: loading-frame-default-eager 'self' https://example.com
+```
+would defer loading  all `<iframe>`s from origins other than `self` and `https://example.com` that do not explicitly set `loading="eager"`  to when they are (almost) visible on the page. 
+
+Similarly, the feature could be set through the `allow` attribute of an inline frame:
+```HTML
+<iframe src="https://example.com" loading="auto" allow="loading-frame-default-eager 'none'"></iframe>
+```
+which regards all the `<iframe>`s with `loading="auto"` or `<iframe>`s that do not set `loading` attribute (hence default to `auto`) as lazily loaded frames. Note that the frame itself is not affected by the policy and possibly loads eagerly.
+
+The Extra Mile
+-----------
+In general the feature could allow an expanded set of enforcement policies with the use of [parametric features](https://github.com/WICG/feature-policy/issues/163). Under a generalized `loading-frame` policy, the following potential values could be supported (in the order of permissiveness):
+  * `default`: the policy does not affect the behavior of the `loading` attribute,
+  * `default-eager-off`: all the `loading="auto"` attributes (and those not set for a `<iframe>`) are regarded as `lazy`,
+  * `eager-off`: all the `loading="eager"` and `loading="auto"` (and unset `<iframe>`s) are interpretted as `loading="lazy"`.
+