Merge pull request #44 from mathiasbynens/patch-1

Clarify distinction between globalThis and the global object

README.md

@@ -36,9 +36,50 @@ var getGlobal = function () {
 
 ## HTML and the `WindowProxy`
 
-In HTML 5, the global object is separated into the `Window` and the `WindowProxy`. New attributes are set on the `Window`, but top-level this has the identity of the `WindowProxy`. The `WindowProxy` forwards all object operations to the underlying `Window`, but as the page changes, the global object maintains the same identity while the underlying `Window` is swapped out.
+In HTML, the global object is separated into the `Window` and the `WindowProxy`. New attributes are set on the `Window`, but top-level `this` has the identity of the `WindowProxy`. The `WindowProxy` forwards all object operations to the underlying `Window`, but as the page changes, `globalThis` maintains the same identity while the underlying `Window` is swapped out.
 
-ES6/ES2015 does not account for the `Window`/`WindowProxy` structure, and simply refers to ”the global object” directly. This specification does the same. If the ECMAScript specification is changed for top-level this to account for `WindowProxy`, then the change should also apply to the definition of this proposal.
+The distinction is observable in the following scenario, with files `parent.html`, `frame-a.html`, and `frame-b.html`. `frame-a.html` has the following source code:
+
+```html
+<script>
+  window.foo = 'a';
+  window.getGlobalThis = () => globalThis;
+</script>
+```
+
+`frame-b.html` has the following source code:
+
+```html
+<script>
+  window.getGlobalThis = () => globalThis;
+</script>
+```
+
+`parent.html`'s source code is:
+
+```html
+<iframe src="frame-a.html"></iframe>
+<script>
+  const frame = frames[0];
+  // The global variable `foo` exists.
+  console.assert(frame.foo === 'a');
+  const before = frame.getGlobalThis();
+  frame.src = 'b.html';
+  frame.onload = () => {
+    // The global variable `foo` has disappeared.
+    console.assert(frame.foo === undefined);
+    const after = frame.getGlobalThis();
+    // But, `globalThis` still has the same identity.
+    console.assert(before === after);
+  };
+</script>
+```
+
+This shows that the global variable `foo` was being stored on the actual global object, which has changed during navigation, but `globalThis` has not changed during navigation. Therefore, `globalThis` is not the global object.
+
+Thus, `globalThis` is observably different from “the global object”, which is not directly accessible from JavaScript.
+
+ES6/ES2015 does not account for the `Window`/`WindowProxy` structure, and simply refers to ”the global object” directly. This specification does the same. If the ECMAScript specification is changed for top-level `this` to account for `WindowProxy`, then the change should also apply to the definition of this proposal.
 
 ## SES interaction