diff --git a/source b/source index 03b99205161..be99ee65fa7 100644 --- a/source +++ b/source @@ -3327,6 +3327,17 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d +
Battery Status
+ +
+ +

The following features are defined in the Battery Status API specification:

+ + + +
@@ -86906,52 +86917,6 @@ interface NavigatorOnLine { implementations are free to limit its size, e.g. by removing old entries from it when new ones are added.

-
- -

A global object is a JavaScript object that is the [[GlobalObject]] field of a - JavaScript realm.

- -

In this specification, all JavaScript - realms are initialized with global objects that are either Window or - WorkerGlobalScope objects.

- -

There is always a 1:1:1 mapping between JavaScript - realms, global objects, and environment settings objects:

- - - -

The relevant settings object for a non-global platform object - o is the environment settings object whose global object is the global object of the - global environment associated with o.

- -
Fetching scripts

The various script-fetching algorithms below have two hooks that may be customized by their @@ -87357,7 +87322,7 @@ interface NavigatorOnLine { -

Calling scripts
+
Calling scripts

To run a classic script given a classic script s and an optional rethrow errors flag:

@@ -87480,7 +87445,8 @@ interface NavigatorOnLine {
    -

  1. Label settings as a candidate entry settings object.

    2. +

  2. Increment settings's realm execution context's entrance + counter by one.

  3. Push settings's realm execution context onto the JavaScript execution context stack; it is now the running JavaScript execution @@ -87494,12 +87460,12 @@ interface NavigatorOnLine {

      -

    1. Stop labeling settings as a candidate entry settings - object.

      2. -

    2. Assert: settings's realm execution context is the running JavaScript execution context.

      3. +

    3. Decrement settings's realm execution context's entrance + counter by one.

      4. +

    4. Remove settings's realm execution context from the JavaScript execution context stack.

      5. @@ -87521,18 +87487,240 @@ interface NavigatorOnLine {
      -

      A JavaScript execution context's settings object is the - settings object of the script in the [[HostDefined]] field in the - ScriptOrModule component of the given JavaScript execution context.

      +

      Each unit of related similar-origin browsing contexts has a global script + clean-up jobs list, which must initially be empty. A global script clean-up job cannot run + scripts, and cannot be sensitive to the order in which other clean-up jobs are executed. The File + API uses this to release blob: URLs.

      -

      The current settings object is the environment settings object of the current - Realm Record.

      +

      When the user agent is to run the global script clean-up jobs, the user agent must + perform each of the jobs in the global script clean-up jobs list and then empty the + list.

      -

      The entry settings object is the settings object of the topmost entry in the JavaScript execution - context stack whose settings object is labeled as a candidate entry settings object.

      +
      Realms, settings objects, and global objects
      + +

      A global object is a JavaScript object that is the [[GlobalObject]] field of a + JavaScript realm.

      + +

      In this specification, all JavaScript + realms are initialized with global objects that are either Window or + WorkerGlobalScope objects.

      + +

      There is always a 1:1:1 mapping between JavaScript + realms, global objects, and environment settings objects:

      + +
        +

      • A JavaScript realm has a [[HostDefined]] field, which contains the Realm's settings object.

        • + +

      • A JavaScript realm has a [[GlobalObject]] field, which contains the Realm's global object.

        • + +

      • Each global object in this specification is created during the initialization of a corresponding JavaScript + realm, known as the global object's + Realm.

        • + +

      • Each global object in this + specification is created alongside a corresponding environment settings object, + known as its relevant settings object.

        + +

      • An environment settings object's realm execution context's + Realm component is the environment settings + object's Realm.

        • + +

      • An environment settings object's Realm then has a [[GlobalObject]] field, which contains the environment settings object's global + object.

        • +
      + +
      + +

      When defining algorithm steps throughout this specification, it is often important to indicate + what JavaScript realm is to be used—or, equivalently, what global object + or settings object is to be used. In general, there are at least four + possibilities:

      + +
      +
      Entry
      +
      This corresponds to the script that initiated the currently running script action: i.e., + the function or script that the user agent called into when it called into author code.
      + +
      Incumbent
      +
      This corresponds to the most-recently-entered author function or script on the stack.
      + +
      Current
      +
      This corresponds to the currently-running function object, including built-in user-agent + functions which might not be implemented as JavaScript. (It is derived from the current + JavaScript realm.)
      + +
      Relevant
      +
      Every platform object has a relevant + Realm. When writing algorithms, the most prominent platform object whose + relevant Realm might be important is the + this value of the currently-running function object. In some cases, there can be other + important relevant Realms, such as those of any + arguments.
      +
      + +

      Note how the entry, incumbent, and current concepts are usable without qualification, + whereas the relevant concept must be applied to + a particular platform object.

      + +
      + +

      Consider the following pages, with a.html being loaded in a browser + window, b.html being loaded in an iframe as shown, and c.html and d.html omitted (they can simply be empty + documents):

      + + 
      <!-- a.html -->
+<!DOCTYPE html>
+<html lang="en">
+<title>Entry page</title>
+
+<iframe src="b.html"></iframe>
+<button onclick="frames[0].hello()">Hello</button>
+
+<!--b.html -->
+<!DOCTYPE html>
+<html lang="en">
+<title>Incumbent page</title>
+
+<iframe src="c.html" id="c"></iframe>
+<iframe src="d.html" id="d"></iframe>
+
+<script>
+  const c = document.querySelector("#c").contentWindow;
+  const d = document.querySelector("#d").contentWindow;
+
+  window.hello = () => {
+    c.print.call(d);
+  };
+</script>
      + +

      Each page has its own browsing context, and thus its own JavaScript + realm, global object, and settings object.

      + +

      When the print() method is called in response to pressing the + button in a.html, then:

      + +
        +

      • The entry Realm is that of a.html.

        • +

      • The incumbent Realm is that of b.html.

        • +

      • The current Realm is that of c.html (since it is the print() method from + c.html whose code is running).

        • +

      • The relevant Realm of the object on which + the print() method is being called is that of d.html.

        • +
      +
      + +

      The incumbent and entry concepts should not be used by new specifications, + and we are considering whether we can remove almost all existing uses. See Bugzilla bug 26603 for incumbent, and Bugzilla bug 27203 for entry.

      + +

      Currently, the incumbent + concept is used in some security checks, and the entry concept is sometimes used to obtain, amongst other + things, the API base URL to parse a URL, used in + scripts running in that unit of related similar-origin browsing contexts.

      + +

      In general, the current concept is what should + be used by specifications going forward. There is an important exception, however. If an algorithm + is creating an object that is to be persisted and returned multiple times (instead of simply + returned to author code right away, and never vended again), it should use the relevant concept with regard to the object on which + the method in question is being executed. This prevents cross-realm calls from causing an object + to store objects created in the "wrong" realm.

      + +
      +

      The navigator.getBattery() method creates + promises in the relevant Realm for the + Navigator object on which it is invoked. This has the following impact: + + 

      <!-- outer.html -->
+<!DOCTYPE html>
+<html lang="en">
+<title>Relevant Realm demo: outer page</title>
+<script>
+  function doTest() {
+    const promise = navigator.getBattery.call(frames[0].navigator);
+
+    console.log(promise instanceof Promise);           // logs false
+    console.log(promise instanceof frames[0].Promise); // logs true
+
+    frames[0].hello();
+  }
+</script>
+<iframe src="inner.html" onload="doTest()"></iframe>
+
+<!-- inner.html -->
+<!DOCTYPE html>
+<html lang="en">
+<title>Relevant Realm demo: inner page</title>
+<script>
+  function hello() {
+    const promise = navigator.getBattery();
+
+    console.log(promise instanceof Promise);        // logs true
+    console.log(promise instanceof parent.Promise); // logs false
+  }
+</script>
      + +

      If the algorithm for the getBattery() method + had instead used the current Realm, all the results + would be reversed. That is, after the first call to getBattery() in outer.html, the + Navigator object in inner.html would be permanently storing + a Promise object created in outer.html's + JavaScript realm, and calls like that inside the hello() + function would thus return a promise from the "wrong" realm. Since this is undesirable, the + algorithm instead uses the relevant Realm, giving + the sensible results indicated in the comments above.

      +
      + +
      + +

      The rest of this section deals with formally defining the entry, incumbent, current, and relevant concepts.

      + +
      Entry
      + +

      All realm execution contexts must contain, as + part of their code evaluation state, an entrance counter value, which is initially + zero. In the process of calling scripts, this value will be + incremented and decremented.

      + +

      With this in hand, we define the entry execution context to be the most recently + pushed entry in the JavaScript execution context stack whose entrance + counter value is greater than zero. The entry Realm + is the entry execution context's Realm component.

      + +

      Then, the entry settings object is the environment settings object of the entry Realm.

      + +

      Similarly, the entry global object is the global object of the entry + Realm.

      + +
      Incumbent

      The incumbent settings object is determined as follows:

      @@ -87546,69 +87734,59 @@ interface NavigatorOnLine { scriptOrModule's [[HostDefined]] field.

    -
    -

    The entry settings object is used to obtain, amongst other things, the API - base URL to parse a URL, used in scripts running in that - unit of related similar-origin browsing contexts.

    +

    Then, the incumbent Realm is the Realm of the incumbent settings + object.

    -

    The incumbent settings object is used in some security checks.

    -
    - -

    The incumbent settings object concept should not be used by new - specifications, and we are considering whether it can be removed from the platform. See Bugzilla bug 26603.

    +

    Similarly, the incumbent global object is the + global object of the incumbent + settings object.

    -
    +
    Current
    -

    Consider the following two pages, with the first being loaded in a browser window and the - second being loaded in the iframe of the first:

    +

    The JavaScript specification defines the current Realm Record, sometimes + abbreviated to "the current Realm".

    - 
    <!-- a/a.html -->
-<!DOCTYPE HTML>
-<html lang="en">
-<title>Outer page</title>
-<iframe src="../b/b.html"></iframe>
-<input type=button onclick="frames[0].hello()" value="Hello">
    +

    Then, the current settings object is the environment settings object of the current + Realm Record.

    - 
    <!-- b/b.html -->
-<!DOCTYPE HTML>
-<html lang="en">
-<title>Inner page</title>
-<script>
- function hello() {
-   location.assign('c.html');
- }
-</script>
    +

    Similarly, the current global object is the global object of the current Realm Record.

    -

    When the button is pressed in the inner frame, the outer page runs script in the inner page. - While the hello() function is running, the entry settings - object is that of the outer file (a/a.html), and the - incumbent settings object is that of the inner file (b/b.html).

    +
    Relevant
    -

    The assign() method uses the entry settings - object to parse the URL, so we end up loading a/c.html, but it uses the incumbent settings object to establish - the source browsing context, from which the referrer is established, so the `Referer` header sent with the request for a/c.html specifies the inner file's URL (the one ending with b/b.html).

    +

    The relevant settings object for a platform object is defined as + follows:

    - +
    +
    If the object is a global object
    +
    Each global object in this specification is created alongside a corresponding + environment settings object; that is its relevant settings object.
    -
    +
    Otherwise
    +
    +

    The relevant settings object for a non-global platform object + o is the environment settings object whose global object is the global object of the + global environment associated with o.

    -
    +

    The "global environment associated with" concept is from the olden + days, before the modern JavaScript specification and its concept of realms. We expect that as the Web IDL specification gets updated, every + platform object will have a Realm associated + with it, and this definition can be re-cast in those terms.

    +
    + -

    Each unit of related similar-origin browsing contexts has a global script - clean-up jobs list, which must initially be empty. A global script clean-up job cannot run - scripts, and cannot be sensitive to the order in which other clean-up jobs are executed. The File - API uses this to release blob: URLs.

    +

    Then, the relevant Realm for a platform + object is the Realm of its + relevant settings object.

    -

    When the user agent is to run the global script clean-up jobs, the user agent must - perform each of the jobs in the global script clean-up jobs list and then empty the - list.

    +

    Similarly, the relevant global object for a + platform object is the global + object of its relevant settings object.

    Killing scripts
    @@ -87683,7 +87861,8 @@ interface NavigatorOnLine {

    1. Assert: queueName is "PromiseJobs". ("ScriptJobs" must not be used by user agents.)

      2. -

    2. Let settings be the current settings object.

      3. +

    3. Let settings be the settings + object of job.[[Realm]].

    4. Queue a microtask, on settings's responsible event loop, to perform the following steps:

      @@ -118564,6 +118743,9 @@ INSERT INTERFACES HERE
      [ATOM]
      (Non-normative) The Atom Syndication Format, M. Nottingham, R. Sayre. IETF.
      +
      [BATTERY]
      +
      (Non-normative) Battery Status API, A. Kostiainen, M. Lamouri. W3C.
      +
      [BCP47]
      Tags for Identifying Languages; Matching of Language Tags, A. Phillips, M. Davis. IETF.
      @@ -118589,7 +118771,7 @@ INSERT INTERFACES HERE
      Unicode Common Locale Data Repository. Unicode.
      [COMPOSITE]
      -
      Compositing and Blending. R. Cabanier, N. Andronikos. W3C.
      +
      Compositing and Blending, R. Cabanier, N. Andronikos. W3C.
      [COMPUTABLE]
      (Non-normative) On computable numbers, with an application to the Entscheidungsproblem, A. Turing. In Proceedings of the London Mathematical Society, series 2, volume 42, pages 230-265. London Mathematical Society, 1937.