Don't require action within a Promise reaction microtask.

Author: jan-ivar

index.bs

@@ -1965,6 +1965,38 @@ See also:
 
 * <a href="https://www.w3.org/2001/tag/doc/promises-guide">Writing Promise-Using Specifications</a>
 
+<h4 id="sync-callbacks">When to use callback functions instead</h4>
+
+<p>If an algorithm requires that callback functions respond
+synchronously (e.g. to take or veto some action), then that is a
+synchronous API, and should not be modelled with a promise. Instead,
+use an explicit callback or event.</p>
+
+<p>In Promise reaction callbacks, you may not require action within
+the same microtask.</p>
+
+<p>This protects promise composition: patterns like <code>await</code>,
+wrapper helpers, logging, <code>Promise.race()</code>, or multiple
+<code>.then()</code> branches all queue an extra microtask and must
+not cause action at a distance.</p>
+
+<div class=example>
+Calling <code>event.preventDefault()</code> in an event handler,
+or choosing a response object inside a
+<code>fetchEvent.respondWith()</code> callback.
+</div>
+<div class="example">
+A non-event example is the [captureController.setFocusBehavior()](https://w3c.github.io/mediacapture-screen-share/#dom-capturecontroller-setfocusbehavior)
+method to push a window the user has chosen to screen-capture, to
+the front. Applications can decide this based on the window chosen.
+But any delay risks click-jacking.
+
+Instead of requiring the method be called synchronously on the
+reaction microtask of the promise from `getDisplayMedia()`, the
+solution was to instead require the method be called on the
+same promise reaction task, with a one second timeout.
+</div>
+
 <h3 id="aborting">Cancel asynchronous APIs/operations using AbortSignal</h3>
 
 If an asynchronous method can be cancelled,
@@ -2131,6 +2163,10 @@ Follow the <a href="https://www.w3.org/2001/tag/doc/promises-guide#one-time-even
 in the <strong><a href="https://www.w3.org/2001/tag/doc/promises-guide">Writing
 Promise-Using Specifications</a></strong> guideline.
 
+<h3 id="promises-and-reaction">Don't use promises for cancelable events</h3>
+
+See <a href="#sync-callbacks">when to use callback functions instead</a>.
+
 <h3 id="promises-and-events">Events should fire before related Promises resolve</h3>
 
 If a Promise-based asynchronous algorithm dispatches events,