Update web integrations doc for events with current approach and rationale

Author: nicolo-ribaudo

Diff for: WEB-INTEGRATION.md

@@ -426,27 +426,126 @@ Event dispatches can be one of the following:
   some web API, but the dispatch happens at a later point. In these cases, the
   context should be tracked along the data flow of the operation, even across
   code running in parallel (but not through tasks enqueued on other agents'
-  event loops). [See below on implicit context
-  propagation](#implicit-context-propagation) for how this data flow tracking
-  should happen.
-
-This classification of event dispatches is the way it should be in theory, as
-well as a long-term goal. However, as we describe later in the section on
-implicit context propagation, for the initial rollout we propose treating the
-vast majority of asynchronous dispatches as if they were browser-originated.
-The exceptions would be:
-
-- The `popstate` event
-- The `message` and `messageerror` events
-- All events dispatched on `XMLHttpRequest` or `XMLHttpRequestUpload` objects
-- The `unhandledrejection` and `rejectionhandled` events on the global object
-  (see below)
-
-> TODO: The exact principle for which event listeners are included in this list is still under discussion.
-
-The list above is not meant to be hard-coded in the events machinery as a "is this event part of that list?" check. Instead, the spec text and browser code that fires
-each of these individual events would be modified so that it keeps track of the
-context in which these events were scheduled (e.g. the context of `window.postMessage` or `xhr.send()`), and so that that context is restored before firing the event.
+  event loops).
+
+For events triggered by JavaScript code (either synchronously or asynchronously),
+the goal is for them to behave equivalently as if they were implemented by a
+JavaScript developer that is not explicitly thinking about AsyncContext propagation:
+listeners for events dispatched either **synchronously** or **asynchronously** from
+JS or from a web API would use the context that API is called with.
+
+<details>
+<summary>Expand this section for examples of the equivalece with JS-authored code</summary>
+
+Let's consider a simple approximation of the `EventTarget` interface, authored in JavaScript:
+```javascript
+class EventTarget {
+  #listeners = [];
+
+  addEventListener(type, listener) {
+    this.#listeners.push({ type, listener });
+  }
+
+  dispatchEvent(event) {
+    for (const { type, listener } of this.#listeners) {
+      if (type === event.type) {
+        listener.call(this, event);
+      }
+    }
+  }
+}
+```
+
+An example _synchronous_ event is `AbortSignal`'s `abort` event. A naive approximation
+in JavaScript would look like the following:
+
+```javascript
+class AbortController {
+  constructor() {
+    this.signal = new AbortSignal();
+  }
+
+  abort() {
+    this.signal.aborted = true;
+    this.signal.dispatchEvent(new Event("abort"));
+  }
+}
+```
+
+When calling `abortController.abort()`, there is a current async context active in the agent. All operations that lead to the `abort` event being dispatched are synchronous and do not manually change the current async context: the active async context will remain the same through the whole `.abort()` process,
+including in the event listener callbacks:
+
+```javascript
+const abortController = new AbortController();
+const asyncVar = new AsyncContext.Variable();
+abortController.signal.addEventListener("abort", () => {
+  console.log(asyncVar.get()); // "foo"
+});
+asyncVar.run("foo", () => {
+  abortController.abort();
+});
+```
+
+Let's consider now a more complex case: the asynchronous `"load"` event of `XMLHttpRequest`. Let's try
+to implement `XMLHttpRequest` in JavaScript, on top of fetch:
+
+```javascript
+class XMLHttpRequest extends EventTarget {
+  #method;
+  #url;
+  open(method, url) {
+    this.#method = method;
+    this.#url = url;
+  }
+  send() {
+    (async () => {
+      try {
+        const response = await fetch(this.#url, { method: this.#method });
+        const reader = response.body.getReader();
+        let done;
+        while (!done) {
+          const { done: d, value } = await reader.read();
+          done = d;
+          this.dispatchEvent(new ProgressEvent("progress", { /* ... */ }));
+        }
+        this.dispatchEvent(new Event("load"));
+      } catch (e) {
+        this.dispatchEvent(new Event("error"));
+      }
+    })();
+  }
+}
+```
+
+And lets trace how the context propagates from `.send()` in the following case:
+```javascript
+const asyncVar = new AsyncContext.Variable();
+const xhr = new XMLHttpRequest();
+xhr.open("GET", "https://example.com");
+xhr.addEventListener("load", () => {
+  console.log(asyncVar.get()); // "foo"
+});
+asyncVar.run("foo", () => {
+  xhr.send();
+});
+```
+- when `.send()` is called, the value of `asyncVar` is `"foo"`.
+- it is synchronously propagated up to the `fetch()` call in `.send()`
+- the `await` snapshots the context before pausing, and restores it (to `asyncVar: "foo"`) when the `fetch` completes
+- the `await`s in the reader loop propagate the context as well
+- when `this.dispatchEvent(new Event("load"))`, is called, the current active async context is thus
+  the same one as when `.send()` was called
+- the `"load"` callback thus runs with `asyncVar` set to `"foo"`.
+
+Note that this example uses `await`, but due to the proposed semantics for `.then` and `setTimeout`
+(and similar APIs), the same would hapepn when using other asynchronicity primitives.
+
+</details>
+
+Event listeners for events dispatched **from the browser** rather than as a consequence of some JS action (e.g. a user clicking on a button) will by default run in the root (empty) context. This is the same
+context that the browser uses, for example, for the top-level execution of scripts.
+
+> NOTE: To keep agents isolated, events dispatched from different agents (e.g. from a worker, or from a cross-origin iframe) will behave as events dispatched by user interaction.
 
 ### Fallback context ([#107](https://github.com/tc39/proposal-async-context/issues/107))