From 71877085fdd32c4d0a9f74208363db6a5e0a73b7 Mon Sep 17 00:00:00 2001
From: Leo Balter <leonardo.balter@gmail.com>
Date: Mon, 12 Apr 2021 12:29:04 -0700
Subject: [PATCH] Meta: Update Explainer for Isolated Realms (#292)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Mathieu Hofman
Co-authored-by: Caridy Patiño
---
 README.md    |   1 +
 explainer.md | 452 ++++++++++++++++++++-------------------------------
 2 files changed, 176 insertions(+), 277 deletions(-)

diff --git a/README.md b/README.md
index e558305..821460f 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,7 @@ See some examples [in the Explainer file](explainer.md).
 
 ## <a name='History'></a>History
 
+* we moved on from the exposed globalThis model to a lean isolated realms API (see #289 and #291)
 * we worked on this during ES2015 time frame, so never went through stages process ([ES6 Realm Objects proto-spec.pdf](https://github.com/tc39/proposal-realms/files/717415/ES6.Realm.Objects.proto-spec.pdf))
 * got punted to later (rightly so!)
 * goal of this proposal: resume work on this, reassert committee interest via advancing to stage 2
diff --git a/explainer.md b/explainer.md
index 73f6613..c0b8554 100644
--- a/explainer.md
+++ b/explainer.md
@@ -3,45 +3,26 @@
 <!-- vscode-markdown-toc -->
 * [Introduction](#Introduction)
 * [API (TypeScript Format)](#APITypeScriptFormat)
-	* [Quick API Usage Example](#QuickAPIUsageExample)
 * [Motivations](#Motivations)
-    * [How does Realms operate?](#Operation)
 * [Clarifications](#Clarifications)
-	* [Terminology](#Terminology)
-	* [The Realm's Global Object](#TheRealmsGlobalObject)
-	* [Evaluation](#Evaluation)
-	* [Module Graph](#ModuleGraph)
-	* [Compartments](#Compartments)
 * [Why not separate processes?](#Whynotseparateprocesses)
 * [Use Cases](#UseCases)
-	* [_Trusted_ Third Party Scripts](#Trusted_ThirdPartyScripts)
-	* [Code Testing](#CodeTesting)
-		* [Running tests in a Realm](#RunningtestsinaRealm)
-		* [Test FWs + Tooling to run tests in a realm](#TestFWsToolingtoruntestsinarealm)
-	* [Codebase segmentation](#Codebasesegmentation)
-	* [Template libraries](#Templatelibraries)
-	* [DOM Virtualization](#DOMVirtualization)
-		* [DOM Virtualization: AMP WorkerDOM Challenge](#DOMVirtualization:AMPWorkerDOMChallenge)
-		* [JSDOM + vm Modules](#JSDOMvmModules)
-	* [Virtualized Environment](#VirtualizedEnvironment)
-		* [DOM mocking](#DOMmocking)
+  * [_Trusted_ Third Party Scripts](#Trusted_ThirdPartyScripts)
+  * [Code Testing](#CodeTesting)
+    * [Running tests in a Realm](#RunningtestsinaRealm)
+    * [Test FWs + Tooling to run tests in a realm](#TestFWsToolingtoruntestsinarealm)
+  * [Codebase segmentation](#Codebasesegmentation)
+  * [Template libraries](#Templatelibraries)
+  * [DOM Virtualization](#DOMVirtualization)
+    * [DOM Virtualization: AMP WorkerDOM Challenge](#DOMVirtualization:AMPWorkerDOMChallenge)
+    * [JSDOM + vm Modules](#JSDOMvmModules)
+  * [Virtualized Environment](#VirtualizedEnvironment)
+    * [DOM mocking](#DOMmocking)
 * [Modules](#Modules)
 * [Integrity](#Integrity)
-	* [Security vs Integrity](#SecurityvsIntegrity)
-* [More Examples](#MoreExamples)
-	* [Example: Simple Realm](#Example:SimpleRealm)
-	* [Example: Importing Module](#Example:ImportingModule)
-	* [Example: Virtualized Contexts](#Example:VirtualizedContexts)
-	* [Example: Simple Subclass](#Example:SimpleSubclass)
-	* [Example: DOM Mocking](#Example:DOMMocking)
-	* [Example: iframes vs Realms](#Example:iframesvsRealms)
-	* [Example: Indirect Evaluation](#Example:IndirectEvaluation)
-	* [Example: Direct Evaluation](#Example:DirectEvaluation)
-	* [Example: Identity Discontinuity](#Example:IdentityDiscontinuity)
-* [Example: Node's vm objects vs Realms](#Example:NodesvmobjectsvsRealms)
+  * [Security vs Integrity](#SecurityvsIntegrity)
 * [Status Quo](#StatusQuo)
 * [Iframes](#Iframes)
-	* [Detachable](#Detachable)
 * [FAQ](#FAQ)
 
 <!-- vscode-markdown-toc-config
@@ -77,26 +58,50 @@ This is The Realms API description in TypeScript format:
 ```ts
 declare class Realm {
     constructor();
-    readonly globalThis: typeof globalThis;
-    import(specifier: string): Promise<Namespace>;
+    importBinding(specifier: string, bindingName: string): Promise<PrimitiveValueOrCallable>;
+    evaluate(sourceText: string): PrimitiveValueOrCallable;
 }
 ```
 
 The proposed specification defines:
 
 - The [`constructor`](https://tc39.es/proposal-realms/#sec-realm).
-- The [`Realm#import()`](https://tc39.es/proposal-realms/#sec-realm.prototype.import) method, equivalent to the `import()` expression.
-- The [`get Realm#globalThis`](https://tc39.es/proposal-realms/#sec-realm.prototype.import) accessor to the Realm's `globalThis`.
+- The [`Realm#importBinding()`](https://tc39.es/proposal-realms/#sec-realm.prototype.importBinding) method, equivalent to the `import()` expression, but capturing a primitive or callable values.
+- The [`get Realm#evaluate`](https://tc39.es/proposal-realms/#sec-realm.prototype.evaluate) method promotes an indirect eval in the realm but only allows the return of primitive or callable values.
+- A new wrapped function exotic object with a custom `[[Call]]` internal that has a shared identity of a connected function from another realm associated to it. This identity is not exposed and there is no way to trace back to connected functions cross-realms in user-land.
 
 ### <a name='QuickAPIUsageExample'></a>Quick API Usage Example
 
-```js
-const realm = new Realm();
-// realms can import module that will execute within it's own environment.
-realm.import('./file.js');
-// realms exposes access to its ordinary global object as a communication
-// channel between the incubator realm and the newly created realm.
-realm.globalThis;
+```javascript
+const red = new Realm();
+
+// realms can import modules that will execute within it's own environment.
+// When the module is resolved, it captured the binding value, or creates a new
+// wrapped function that is connected to the callable binding.
+const redAdd = await red.importBinding('./inside-code.js', 'add');
+
+// redAdd is a wrapped function exotic object that chains it's call to the
+// respective imported binding.
+let result = redAdd(2, 3);
+
+console.assert(result === 5); // yields true
+
+// The evaluate method can provide quick code evaluation within the constructed
+// realm without requiring any module loading, while it still requires CSP
+// relaxing.
+globalThis.someValue = 1;
+red.evaluate('globalThis.someValue = 2'); // Affects only the Realm's global
+console.assert(globalThis.someValue === 1);
+
+// The wrapped functions can also wrap other functions the other way around.
+const setUniqueValue =
+    await red.importBinding('./inside-code.js', 'setUniqueValue');
+
+/* setUnitValue = (cb) => (cb(globalThis.someValue) * 2); */
+
+result = setUniqueValue((x) => x ** 3);
+
+console.assert(result === 16); // yields true
 ```
 
 ## <a name='Motivations'></a>Motivations
@@ -107,7 +112,7 @@ These programs must currently contend for the global shared resources, specifica
 
 Attempting to solve these problems with existing DOM APIs will require to implement an asynchronous communication protocol, which is often a deal-breaker for many use cases. It usually just adds complexity for cases where a same-process Realm is sufficient. It's also very important that values can be immediately shared. Other communications require data to be serialized before it's sent back and forth.
 
-__The primary goal of this proposal is to provide a proper mechanism to control the execution of a program, providing a new global object, a new set of intrinsics, no default access to the incubator realm's global object, a separate module graph and synchronous communication with the incubator realm__.
+__The primary goal of this proposal is to provide a proper mechanism to control the execution of a program, providing a new global object, a new set of intrinsics, no access to objects cross-realms, a separate module graph and synchronous communication between both realms__.
 
 In addition to the motivations given above, another commonly-cited motivation is virtualization and portability. Some of the functionalities of the VM module in Node can also be standardized, providing the infrastructure for virtualization of JavaScript programs in all environments.
 
@@ -119,7 +124,7 @@ Realms is an often-requested feature from developers, directly or indirectly. It
 
 Realms execute code with the same JavaScript heap as the surrounding context where the Realm is created. Code runs synchronously in the same thread. Note: The surrounding context is often referenced as the _incubator realm_ within this proposal.
 
-Same-origin iframes also create a new global object which is synchronously accessible. Realms differ from same-origin iframes by omitting Web APIs such as the DOM.
+Same-origin iframes also create a new global object which is synchronously accessible. Realms differ from same-origin iframes by omitting Web APIs such as the DOM, and async config for code injected through dynamic imports. Problems related to identity discontinuity exist in iframes but are not a possibility in Realms as object values are not transferred cross-realms in user land. The only connection exists internally through wrapped functions.
 
 Sites like Salesforce.com make extensive use of same-origin iframes to create such global objects. Our experience with same-origin iframes motivated us to steer this proposal forward, which has the following advantages:
 
@@ -127,7 +132,7 @@ Sites like Salesforce.com make extensive use of same-origin iframes to create su
 - Tailoring up [the exposed set of APIs into the code](#VirtualizedEnvironment) within the Realm provides a better developer experience for a less expensive work compared to tailoring down a full set of exposed APIs - e.g. iframes - that includes handling presence of `[LegacyUnforgeable]` attributes like `window.top`.
 - We hope the usage of Realms will be somewhat lighter weight (both in terms of memory and CPU) for the browser if compared to iframes, especially when frameworks rely on several Realms in the same application.
 - Realms are not accessible from by traversing the DOM of the incubator realm. This will ideal and/or better approach compared to attaching iframes elements and their contentWindow to the DOM. [Detaching iframes](#Iframes) would even add a new own set of problems.
-- A newly created realm does not have immediate access to any object from the incubator realm and won't have access to `window.top` as iframes would.
+- A newly created realm does not have immediate access to any object from the incubator realm - and vice-versa - and won't have access to `window.top` as iframes would.
 
 Realms are complementary to stronger isolation mechanisms such as Workers and cross-origin iframes. They are useful for contexts where synchronous execution is an essential requirement, e.g., emulating the DOM for integration with third-party code. Realms avoid often-prohibitive serialization overhead by using a common heap to the surrounding context.
 
@@ -153,22 +158,23 @@ Instances of Realm Objects and their Global Objects have their lifeline to their
 
 ### <a name='Evaluation'></a>Evaluation
 
-The Realms API does not introduce a new way to evaluate code, it is subject to the existing evaluation mechanisms such as the [Content-Security-Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy).
+Any code evaluation mechanism in this API is subject to the existing the [Content-Security-Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy).
 
-If the CSP directive from a page disallows `unsafe-eval`, it prevents synchronous evaluation in the Realm. E.g.: `Realm#globalThis.eval`, `Realm#globalThis.Function`.
+If the CSP directive from a page disallows `unsafe-eval`, it prevents synchronous evaluation in the Realm, i.e.: `Realm#evaluate`.
 
-The CSP of a page can also set directives like the `default-src` to prevent a Realm from using `Realm#import()`.
+The CSP of a page can also set directives like the `default-src` to prevent a Realm from using `Realm#importBinding()`.
 
 ### <a name='ModuleGraph'></a>Module Graph
 
 Each instance of Realms must have its own Module Graph.
 
-```js
+```javascript
 const realm = new Realm();
 
 // imports code that executes within its own environment.
-const { doSomething } = await realm.import('./file.js');
+const doSomething = await realm.import('./file.js', 'redDoSomething');
 
+// This call chains to the realm's redDoSomething
 doSomething();
 ```
 
@@ -178,7 +184,7 @@ This proposal does not define any virtualization mechanism for host behavior. Th
 
 A new [Compartment](https://github.com/tc39/proposal-compartments) provides a new Realm constructor. A Realm object from a Compartment is subject to the Compartment's host virtualization mechanism.
 
-```js
+```javascript
 const compartment = new Compartment(options);
 const VirtualizedRealm = compartment.globalThis.Realm;
 const realm = new VirtualizedRealm();
@@ -216,19 +222,21 @@ We acknowledge that applications need a quick and simple execution of Third Part
 
 The Realms API provides integrity preserving semantics - including built-ins - of root and incubator Realms, setting specific boundaries for the Environment Records.
 
-Third Party Scripts can be executed in a non-blocking asynchronous evaluation through the `Realm#import()`.
+Third Party Scripts can be executed in a non-blocking asynchronous evaluation through the `Realm#importBinding()`.
 
-There is no need for immediate access to the application globals - e.g. `window`, `document`. This comes as a convenience for the application that can provide - or not - values and API in different ways, like frozen properties set in the `Realm#globalThis`. This also creates several opportunities for customization with the Realm Globals and prevent collision with other global values and other third party scripts.
+There is no need for immediate access to the application globals - e.g. `window`, `document`. This comes as a convenience for the application that can provide - or not - values and API in different ways. This also creates several opportunities for customization with the Realm Globals and prevent collision with other global values and other third party scripts.
 
-```js
-import { fmw } from 'pluginFramework';
+```javascript
 const realm = new Realm();
 
-// fmw becomes available in the Realm
-realm.globalThis.fmw = fmw;
+// pluginFramework and pluginScript become available in the Realm
+const [ init, ready ] = await Promise.all([
+    realm.importBinding('./pluginFramework.js', 'init'),
+    realm.importBinding('./pluginScript.js', 'ready'),
+]);
 
 // The Plugin Script will execute within the Realm
-await realm.import('./pluginScript.js');
+init(ready);
 ```
 
 ### <a name='CodeTesting'></a>Code Testing
@@ -239,27 +247,21 @@ Testing code can run autonomously within the boundaries set from the Realm objec
 
 #### <a name='RunningtestsinaRealm'></a>Running tests in a Realm
 
-```js
+```javascript
 import { test } from 'testFramework';
 const realm = new Realm();
 
-realm.globalThis.test = test;
-await realm.import('./main-spec.js');
-
-test.report();
-```
-
-#### <a name='TestFWsToolingtoruntestsinarealm'></a>Test FWs + Tooling to run tests in a realm
-
-```js
-const realm = new Realm();
-const [ framework, { tap } ] = await Promise.all([
- realm.import('testFramework'),
- realm.import('reporters')
+const [ runTests, getReportString, suite ] = await Promise.all([
+    realm.importBinding('testFramework', 'runTests'),
+    realm.importBinding('testFramework', 'getReportString'),
+    realm.importBinding('./my-tests.js', 'suite'),
 ]);
 
-framework.use(tap);
-await realm.import('./main-spec.js');
+// start tests execution
+runTests(suite);
+
+// request a tap formatted string of the test results when they are ready
+getReportString('tap', res => console.log(res));
 ```
 
 ### <a name='Codebasesegmentation'></a>Codebase segmentation
@@ -268,19 +270,7 @@ A big codebase tend to evolve slowly and soon becomes legacy code. Old code vs n
 
 Modifying code to resolve a conflict (e.g.: global variables) is non-trivial, specially in big codebases.
 
-The Realms API can provide a _lightweight_ mechanism to preserve the integrity of the intrinsics.0 Therefore, it could isolate libraries or logical pieces of the codebase per Realm.
-
-### <a name='Templatelibraries'></a>Template libraries
-
-Code generation should not be subject to pollution (global, prototype, etc.). E.g.: Lodash's `_.template()` uses `Function(...)` to create a compiled template function, instead it could use a Realm to avoid leaking global variables. The same Realm could be reused multiple times.
-
-```js
-var compiled = _.template(
-'<% _.forEach(users, function(user) { %><li><%- user %></li><% }); %>'
-);
-
-compiled({ users: ['user1', 'user2'] });
-```
+The Realms API can provide a _lightweight_ mechanism to preserve the integrity of the intrinsics. Therefore, it could isolate libraries or logical pieces of the codebase per Realm.
 
 ### <a name='DOMVirtualization'></a>DOM Virtualization
 
@@ -288,14 +278,13 @@ We still want things to interact with the DOM without spending any excessive amo
 
 It is important for applications to emulate the DOM as best as possible. Requiring authors to change their code to run in our virtualized environment is difficult. Specially if they are using third party libraries.
 
-```js
-import virtualDocument from 'virtual-document';
-
+```javascript
 const realm = new Realm();
 
-realm.globalThis.document = virtualDocument;
+const initVirtualDocument = await realm.importBinding('virtual-document', 'init');
+await realm.importBinding('./publisher-amin.js', 'symbolId');
 
-await realm.import('./publisher-amin.js');
+init();
 ```
 
 #### <a name='DOMVirtualization:AMPWorkerDOMChallenge'></a>DOM Virtualization: AMP WorkerDOM Challenge
@@ -316,52 +305,69 @@ The Realms API provides a single API for this virtualization in both browsers an
 
 The usage of different realms allow customized access to the global environment. To start, The global object could be immediately frozen.
 
-```js
-let realm = new Realm();
+```javascript
+const realm = new Realm();
+
+realm.evaluate('Object.freeze(globalThis), 0');
+
+// or without CSP relaxing:
 
-Object.freeze(realm.globalThis);
+const freezeRealmGlobal = await realm.importBinding('./inside-code.js', 'reflectFreezeRealmGlobal');
+
+/**
+ * inside-code.js
+ * 
+ * export function reflectFreezeRealmGlobal() {
+ *   try {
+ *     Object.freeze(globalThis);
+ *   catch {
+ *     return false;
+ *   }
+ *   return true;
+ * }
+ **/
+
+freezeRealmGlobal();
 ```
 
 In web browsers, this is currently not possible. The way to get manage new Realms would be through iframes, but they also share a window proxy object.
 
-```js
-let iframe = document.createElement('iframe');
+```javascript
+const iframe = document.createElement('iframe');
 document.body.appendChild(iframe);
 const rGlobal = iframe.contentWindow; // same as iframe.contentWindow.globalThis
 
 Object.freeze(rGlobal); // TypeError, cannot freeze window proxy
 ```
 
-The same iframe approach won't also have a direct access to import modules dynamically. The usage of `realm.import('./file.js');` is possible instead of roughly using eval functions or setting _script type module_ in the iframe, if available.
+The same iframe approach won't also have a direct access to import modules dynamically. The usage of `realm.importBinding` is possible instead of roughly using eval functions or setting _script type module_ in the iframe, if available.
 
 #### <a name='DOMmocking'></a>DOM mocking
 
 The Realms API allows a much smarter approach for DOM mocking, where the globalThis can be setup in userland:
 
-```js
+```javascript
 const realm = new Realm();
 
-await installFakeDOM(realm.globalThis);
+const installFakeDOM = await realm.importBinding('./fakedom.js', 'default');
 
-// Custom properties are now added to the Realm such as
-realm.globalThis.document;
-realm.globalThis.top;
-realm.globalThis.location;
+// Custom properties can be added to the Realm
+installFakeDOM();
 ```
 
 This code allows a customized set of properties to each new Realm - e.g. `document` - and avoid issues on handling immutable accessors/properties from the Window proxy. e.g.: `window.top`, `window.location`, etc..
 
 This explainer document speculates a `installFakeDOM` API to set up a proper frame emulation. We understand there might be many ways to explore how to emulate frames with plenty of room for improvement, as seen in [some previous discussions](https://github.com/tc39/proposal-realms/issues/268#issuecomment-674338593), as in the following pseudo-code:
 
-```js
-function installFakeDOM(realmGlobalThis) {
-    const someRealmIntrinsicsNeededForWrappers = extractIntrinsicsFromGlobal(realmGlobalThis);
-    Object.defineProperties({
-         document: createFakeDocumentDescriptor(someRealmIntrinsicsNeededForWrappers),
-         Element: createFakeElementDescriptor(someRealmIntrinsicsNeededForWrappers),
-         Node: ...
-         ... // all necessary DOM related globals should be defined here
-    });
+```javascript
+export default function() {
+  const someRealmIntrinsicsNeededForWrappers = extractIntrinsicsFromGlobal(customGlobalThis);
+  Object.defineProperties(globalThis, {
+    document: createFakeDocumentDescriptor(someRealmIntrinsicsNeededForWrappers),
+    Element: createFakeElementDescriptor(someRealmIntrinsicsNeededForWrappers),
+    Node: ...
+    ... // all necessary DOM related globals should be defined here
+  });
 }
 
 function createFakeDocumentDescriptor(someIntrinsics) {
@@ -372,9 +378,9 @@ function createFakeDocumentDescriptor(someIntrinsics) {
      };
 }
 
-function extractIntrinsicsFromGlobal(realmGlobalThis) {
+function extractIntrinsicsFromGlobal(customGlobalThis) {
    return {
-       Proxy: realmGlobalThis.Proxy,
+       Proxy,
        ObjectPrototype: Object.prototype,
        create: Object.create,
        ... // whatever you need to facilitate the creation of proper identities for the fake DOM
@@ -382,17 +388,15 @@ function extractIntrinsicsFromGlobal(realmGlobalThis) {
 }
 ```
 
-That's one option to use proxies, notice that the `Proxy` constructor used is from the Realm, same for any proxy handler, or object/function/array accessible from inside the realm (e.g.: the one produced by `createHandlerWithDistortionsForDocument` should be an object with `__proto__` set to `realmGlobalThis.Object.prototype`, this helps with the errors identity). Again, identity issues are hard to solve when multiple realms are playing together, but libraries and frameworks can tackle that at the lower level.
-
 ## <a name='Modules'></a>Modules
 
-In principle, the Realm proposal does not provide the controls for the module graphs. Every new Realm initializes its own module graph, while any invocation to `Realm.prototype.import()` method, or by using `import()` when evaluating code inside the realm, will populate this module graph. This is analogous to same-domain iframes, and VM in nodejs.
+In principle, the Realm proposal does not provide the controls for the module graphs. Every new Realm initializes its own module graph, while any invocation to `Realm.prototype.importBinding()` method, or by using `import()` when evaluating code inside the realm through wrapped functions, will populate this module graph. This is analogous to same-domain iframes, and VM in nodejs.
 
-However, the [Compartments]() proposal plans to provide the low level hooks to control the module graph per Realm. This is one of the intersection semantics between the two proposals.
+However, the [Compartments](https://github.com/tc39/proposal-compartments) proposal plans to provide the low level hooks to control the module graph per Realm. This is one of the intersection semantics between the two proposals.
 
 ## <a name='Integrity'></a>Integrity
 
-We believe that realms can be a good complement to integrity mechanisms by providing ways to evaluate code who access different object graphs (different global objects) while maintaining the integrity of the outer realm. A concrete example of this is the Google's AMP current mechanism:
+We believe that realms can be a good complement to integrity mechanisms by providing ways to evaluate code across different object graphs (different global objects) while maintaining the integrity of both realms. A concrete example of this is the Google's AMP current mechanism:
 
 * Google News App creates multiples sub-apps that can be presented to the user.
 * Each sub-app runs in a cross-domain iframe (communicating with the main app via post-message).
@@ -404,164 +408,95 @@ There are many examples like this for the web: Google Sheets, Figma's plugins, o
 
 There are also other more exotic cases in which measuring of time ("security") is not a concern, especially in IOT where many devices might not have process boundaries at all. Or examples where security is not a concern, e.g.: test runners like jest (from facebook) that relies on nodejs, JSDOM and VM contexts to execute individual tests while sharing a segment of the object graph to achieve the desired performance budget. No doubts that this type of tools are extremely popular these days, e.g.: JSDOM has 10M installs per week according to NPM's registry.
 
-## <a name='MoreExamples'></a>More Examples
-
-### <a name='Example:ImportingModule'></a>Example: Importing Module
-
-```js
-let r = new Realm();
-const { x } = await r.import('/path/to/foo.js');
-```
-
-In this example, the new realm will fetch, and evaluate the module, and extract the `x` named export from that module namespace. `Realm.prototype.import` is equivalent to the dynamic import syntax (e.g.: `const { x } = await import('/path/to/foo.js');` from within the realm. In some cases, evaluation will not be available (e.g.: in browsers, CSP might block unsafe-eval), while importing from module is still possible.
-
 ### <a name='Example:VirtualizedContexts'></a>Example: Virtualized Contexts
 
 Importing modules allow us to run asynchronous executions with set boundaries for access to global environment contexts.
 
 - `main.js`:
 
-```js
-globalThis.DATA = "a global value";
-
-let r = new Realm();
-
-// r.import is equivalent to the dynamic import expression
-// It provides asynchronous execution, without creating or relying in a
-// different thread or process.
-r.import("./sandbox.js").then(({test}) => {
+```javascript
+globalThis.blueValue = "a global value";
 
-  // globals in this root realm are not leaked
-  test("DATA"); // undefined
+const r = new Realm();
 
-  let desc = test("Array"); // {writable: true, enumerable: false, configurable: true, value: ƒ}
-  let Arr = desc.value;
+r.importBinding("./sandbox.js", "test").then(test => {
 
-  Arr === r.globalThis.Array; // true
-  Arr === Array; // false
-
-  // foo and bar are immediately visible as globals here.
+  // globals in the incubator realm are not leaked to the constructed realm
+  test("blueValue"); // undefined
+  test("redValue"); // 42
 });
 ```
 
 - `sandbox.js`:
 
-```js
-// DATA is not available as a global name here
+```javascript
+// blueValue is not available as a global name here
 
-// Names here are not leaked to the root realm
-var foo = 42;
-globalThis.bar = 39;
+// Names here are not leaked to the incubator realm
+globalThis.redValue = 42;
 
 export function test(property) {
-
-  // Built-ins like `Object` are included.
-  return Object.getPropertyDescriptor(globalThis, property);
+  return globalThis[property];
 }
 ```
 
-### <a name='Example:SimpleSubclass'></a>Example: Simple Subclass
-
-```js
-class EmptyRealm extends Realm {
-  constructor(...args) {
-    super(...args);
-    let globalThis = this.globalThis;
-
-    // delete global descriptors:
-    delete globalThis.Math;
-    ...
-  }
-}
-```
-
-In the example above, the global object of a newly created realm of `EmptyRealm` will have no global `Math` available.
-
-### <a name='Example:DOMMocking'></a>Example: DOM Mocking
-
-```js
-const realm = new Realm();
-
-await installFakeDOM(realm.globalThis);
-
-// Custom properties are now added to the Realm such as
-realm.globalThis.document;
-realm.globalThis.top;
-realm.globalThis.location;
-```
-
 ### <a name='Example:iframesvsRealms'></a>Example: iframes vs Realms
 
-If you're using anonymous iframes today to "evaluate" javascript code in a different realm, you can replace it with a new Realm, as a more performant option, e.g.:
+If you're using anonymous iframes today to "evaluate" javascript code in a different realm, you can replace it with a new Realm, as a more performant option, without identity discontinuity, e.g.:
 
-```js
+```javascript
 const globalOne = window;
 let iframe = document.createElement('iframe');
 document.body.appendChild(iframe);
-const globalTwo = iframe.contentWindow;
-```
-
-will become:
-
-```js
-const globalOne = window;
-const globalTwo = new Realm().globalThis;
-```
-
-### <a name='Example:IndirectEvaluation'></a>Example: Indirect Evaluation
-
-This operation should be equivalent, in both scenarios:
+const iframeArray = iframe.contentWindow.Array;
 
-```js
-globalOne.eval('1 + 2'); // yield 3
-globalTwo.eval('1 + 2'); // yield 3
-```
-
-### <a name='Example:DirectEvaluation'></a>Example: Direct Evaluation
+console.assert(iframeArray !== Array);
 
-This operation should be equivalent, in both scenarios:
+const list = iframeArray('a', 'b', 'c');
 
-```js
-globalOne.eval('eval("1 + 2")'); // yield 3
-globalTwo.eval('eval("1 + 2")'); // yield 3
+list instanceof Array; // false
+[] instanceof iframeArray; // false
+Array.isArray(list); // true
 ```
 
-### <a name='Example:IdentityDiscontinuity'></a>Example: Identity Discontinuity
-
-Considering that you're creating a brand new realm, with its brand new global variable,
-the identity discontinuity is still present, just like in the iframe example:
-
-```js
-let a1 = globalOne.eval('[1,2,3]');
-let a2 = globalTwo.eval('[1,2,3]');
-a1.prototype === a2.prototype; // yield false
-a1 instanceof globalTwo.Array; // yield false
-a2 instanceof globalOne.Array; // yield false
-```
+This code is **not** possible with the Realms API! Non-primitive values are not transfered cross-realms using the Realms API.
 
 ## <a name='Example:NodesvmobjectsvsRealms'></a>Example: Node's vm objects vs Realms
 
-If you're using node's `vm` module today to "evaluate" javascript code in a different realm, you can replace it with a new Realm, e.g.:
+If you're using node's `vm` module today to "evaluate" javascript code in a different realm, you can replace some of its usage with a new Realm, e.g.:
 
-```js
+```javascript
 const vm = require('vm');
-const script = new vm.Script('this');
-const globalOne = globalThis;
-const globalTwo = script.runInContext(new vm.createContext());
+const script = new vm.Script(`
+function add(a, b) {
+  return a + b;
+}
+
+const x = add(1, 2);
+`);
+script.runInContext(new vm.createContext());
 ```
 
 will become:
 
-```js
-const globalOne = globalThis;
-const globalTwo = new Realm().globalThis;
+```javascript
+const realm = new Realm();
+
+const result = realm.evaluate(`
+function add(a, b) {
+  return a + b;
+}
+
+const x = add(1, 2);
+x;
+`);
 ```
 
-_Note: these two are equivalent in functionality._
+__Note__: these two are rough equivalents in functionality only. The `vm` API still has some extended capabilities and ergonomics, even if it fundamentally allow code execution in a different realm.
 
 ## <a name='StatusQuo'></a>Status Quo
 
-Using VM module in nodejs, and same-domain iframes in browsers. Although, VM modules in node is a very good approximation to this proposal, iframes are problematic. 
+The current status quo is using VM module in nodejs, and same-domain iframes in browsers. Although, VM modules in node is a very good approximation to this proposal, iframes are problematic.
 
 ## <a name='Iframes'></a>Iframes
 
@@ -569,13 +504,14 @@ Developers can technically already create a new Realm by creating a new same-dom
 
 * the global object of the iframe is a window proxy, which implements a bizarre behavior, including its unforgeable proto chain.
 * There are multiple ~~unforgeable~~ unvirtualizable objects due to the DOM semantics, this makes it almost impossible to eliminate certain capabilities while downgrading the window to a brand new global without DOM.
-* The global `top` reference cannot be redefined and leaks a reference to another global object. The only way to null out this behavior is to __detach__ the iframe, which imposes other problems, the more relevant is dynamic `import()` calls.
+* The global `top` reference cannot be redefined and leaks a reference to another global object. The only way to null out this behavior is to __detach__ the iframe, which imposes other problems, the more relevant being a restriction to dynamic `import()` calls.
+* Exposure of cross-realms objects with identity discontinuity.
 
 ### <a name='Detachable'></a>Detachable
 
 For clarifications, the term detachable means an iframe pulled out from the DOM tree:
 
-```js
+```javascript
 var iframe = document.createElement("iframe");
 
  // attaching the iframe to the DOM tree
@@ -597,37 +533,11 @@ iframeWindow.top;
 
 ### So do Realms only have the ECMAScript APIs available?
 
-Yes! It only exposes a new copy of the built-ins from ECMAScript, but [it allows extensions defined by each host](https://tc39.es/proposal-realms/#sec-realm).
-
-```
-// Proposal:
-
-Realm ()
-
-...
-11. Perform ? SetDefaultGlobalBindings(O.[[Realm]]).
-...
-```
-
-```
-// ECMAScript
-
-SetDefaultGlobalBindings ( realmRec )
-
-1. Let global be realmRec.[[GlobalObject]].
-2. For each property of the Global Object specified in clause 18, do
-...
-
-18 The Global Object
-
-...
-- may have host defined properties in addition to the properties defined in this specification. This may include a property whose value is the global object itself.
-
-```
+Yes! It only creates a new copy of the built-ins from ECMAScript. Although, we have open discussions about additional [HTML properties](https://github.com/tc39/proposal-realms/issues/284) or [some intrinsics subset](https://github.com/tc39/proposal-realms/issues/288).
 
 ### Most libraries won't work unless they add dependencies manually
 
-> Doesn't this mean that most libraries won't work unless to add its dependencies manually, like `realm.globalThis.fetch = fetch`. Like we could see people using this even to isolate WebAssembly code, thought that requires you adding the methods needed for that.
+> Doesn't this mean that most libraries won't work unless to add its dependencies manually. Like we could see people using this even to isolate WebAssembly code, thought that requires you adding the methods needed for that.
 
 Absolutely, this is equivalent to what happens to [Node VM](https://nodejs.org/api/vm.html) today as a low level API prior art. As a developer you need to setup the environment to execute code.
 
@@ -635,18 +545,6 @@ Ideally the Realms would arrive a clean state, allowing tailoring for what is ne
 
 Considering all the trade offs, the clean state seems the best option, in our opinion. It allows tailoring for multiple purposes and comprehends more use cases.
 
-### The top-level Realm cannot be accessed
-
-> We are also a bit afraid that regular developers will have a hard time understanding all these concepts (realms, globals, this) and how they relate to each other: realms, like what is a realm really, especially since the top-level realm (like the one with window === globalThis) cannot be accessed as a Realm object.
-
-Executed code doesn't need to know it's in a realm, this is designed to be a concern for those setting the realm up. Ideally, code executed in a realm would run seamlessly. There is prior art for this (iframes, Workers, node.vm).
-
-_Additional feedback from @littledan:_
-
-One thing to understand here is that Realms are generally intended to be a sort of metaprogramming construct, which would be used by frameworks and libraries to build emulated JS environments for developers. I understand the feedback that this concept may be difficult for JS developers to understand; probably an introduction in the explainer to show how múltiple globals in JS already work would help make this document more accessible. Either way, it is an underlying primitive in the platform.
-
-### Realm MVP or max/min
-
-> Maybe for consistency sake it would make sense to have an accessor to expose it as a realm, thought currently the only thing exposed is `globalThis` and `import` - but we assume that could be extended in the future.
+### Exploration ahead
 
-The initial Realms proposal had more content and more ways to access things. We tried to build a MVP and hope we can explore expansions of the API in the future.
+There is more to explore ahead for Realms, but not yet for this current proposal. The current API is good enough to enable synchronous execution of code and membranes implementation, even if setup might require async import for code injection.