Close Watcher API

1. Close signals

(This section could be introduced as a new subsection of [HTML]'s User interaction section.)

In an implementation-defined (and likely device-specific) manner, a user can send a close signal to the user agent. This indicates that the user wishes to close something which is currently being shown on the screen, such as a popup, menu, dialog, picker, or display mode.

Whenever the user agent receives a potential close signal targeted at a Document document, it must perform the following close signal steps:

1. If document’s fullscreen element is non-null, then fully exit fullscreen and return.

   This does not fire any relevant event, such as keydown; it only fires fullscreenchange.

2. Fire any relevant event, per UI Events or other relevant specifications. [UI-EVENTS]

   As an example of a relevant event that is outside of the model given in UI Events, current thinking is that assistive technology would synthesize an Esc keydown and keyup event sequence when the user sends a close signal by using a dimiss gesture.

   If multiple such events are fired, the user agent must pick one for the purposes of the following steps.

   For example, it is typical on desktop platforms for pressing down on the Esc key to be a close signal. So, if assistive technology is synthesizing both keydown and keyup events, then it would likely pick the keydown event for the next steps, to better match behavior of desktop platforms without assistive technology in play.

3. If such an event was fired, and its canceled flag is set, then return.

4. If such an event was fired, then perform the following steps within the same task as that event was fired in, immediately after firing the event. Otherwise, queue a global task on the user interaction task source given document’s relevant global object to perform the following steps.

5. If document is not fully active, then return.

6. Let closedSomething be the result of signaling close watchers on document’s relevant global object.

7. If closedSomething was true, then return.

8. Otherwise, there was nothing watching for a close signal. The user agent may instead interpret this interaction as some other action, instead of as a close signal.

On a desktop platform where Esc is the close signal, the user agent will first fire an appropriately-initialized keydown event. If the web developer intercepts this event and calls preventDefault(), then nothing further happens. But if the event is fired without being canceled, then the user agent proceeds to signal close watchers.

On Android where the back button is a potential close signal, no event is involved, so when the user agent determines that the back button represents a close signal, it queues a task to signal close watchers. If there is a close watcher on the close watcher stack, then that will get triggered; otherwise, the user agent will interpret the back button press as a request to traverse the history by a delta of −1.

1.1. Close watcher infrastructure

Each Window has a close watcher stack, a list of close watchers, initially empty.

It isn’t quite a proper stack, as items can get removed from the middle of it if a close watcher is destroyed or closed via web developer code. User-initiated close signals always act on the top of the close watcher stack, however.

Each Window has a timestamp of last activation used for close watchers. This is either a DOMHighResTimeStamp value, positive infinity, or negative infinity (i.e. the same value space as the last activation timestamp). It is initially positive infinity.

This value is used to ensure that a given user activation only enables a single CloseWatcher cancel or dialog cancel event to be fired, per user activation. This is different than requiring transient activation to fire the event, because we want to allow the event to happen arbitrarily long after the user activation.

A close watcher is a struct with the following items:

• A window, a Window.

• A cancel action, a list of steps. These steps can never throw an exception, and return either true (to indicate the caller will proceed to the close action) or false (to indicate the caller will bail out).

• A close action, a list of steps. These steps can never throw an exception.

• An was created with user activation boolean.

• An is grouped with previous boolean.

• An is running cancel action boolean, initially false.

The is grouped with previous boolean is set if a close watcher is created without transient activation. (Except the very first close watcher in the close watcher stack that is created without transient activation, which gets a pass on this restriction.) It causes a user-triggered close signal to close all such grouped-together close watchers, thus ensuring that web developers can’t make close signals ineffective by creating an excessive number of close watchers which all intercept the signal.

1.2. Close watcher API

[Exposed=Window]
interface CloseWatcher : EventTarget {
  constructor(optional CloseWatcherOptions options = {});

  undefined destroy();
  undefined close();

  attribute EventHandler oncancel;
  attribute EventHandler onclose;
};

dictionary CloseWatcherOptions {
  AbortSignal signal;
};

watcher = new CloseWatcher()

watcher = new CloseWatcher({ signal })

Attempts to create a new CloseWatcher instance.

If the signal option is provided, watcher can be destroyed (as if by watcher.destroy()) by aborting the given AbortSignal.

If any close watcher (including both CloseWatcher objects and modal dialog elements) is already active, and the Window does not have transient user activation, then the resulting CloseWatcher will be closed together with that already-active close watcher in response to any close signal.

watcher.destroy()

Deactivates this CloseWatcher instance, so that it will no longer receive close events and so that new independent CloseWatcher instances can be constructed.

This is intended to be called if the relevant UI element is closed in some other way than via a close signal, e.g. by pressing an explicit "Close" button.

watcher.close()

Acts as if a close signal was sent targeting this CloseWatcher instance, by firing a cancel and close event, and deactivating the close watcher as if destroy() was called.

This is a helper utility that can be used to consolidate closing logic into the close event handler, by having all non-close signal closing affordances call close().

Each CloseWatcher has an internal close watcher, which is a close watcher.

The destroy() method steps are to destroy this's internal close watcher.

The close() method steps are to close this's internal close watcher.

Objects implementing the CloseWatcher interface must support the oncancel and onclose event handler IDL attribute, whose event handler event types are respectively cancel and close.

2. Updates to other specifications

2.1. Fullscreen

Replace the sentence about "If the end user instructs..." in Fullscreen API § 4 UI with the following:

If the user initiates a close signal, this will trigger the fully exit fullscreen algorithm as part of the close signal steps. This takes precedence over any close watchers.

2.2. The dialog element

Update HTML’s The dialog element section as follows: [HTML]

Each dialog element has a close watcher, which is a close watcher or null, initially null.

Remove the "Canceling dialogs" section entirely. It is now handled entirely by the infrastructure in § 1 Close signals and the creation of a close watcher.

Modify the close the dialog steps to destroy the dialog's close watcher and set it to null, if it is not already null.

Similarly, modify the "If at any time a dialog element is remo ved from a Document" steps to do the same.

3. Security and privacy considerations

3.1. Security considerations

The main security consideration with this API is preventing abusive pages from hijacking the fallback behavior in the last part of the close signal steps. A concrete example is on Android, where the close signal is the software back button, and this fallback behavior is to traverse the history by a delta of −1. If developers could always intercept Android back button presses via CloseWatcher instances and dialog elements, then they could effectively break the back button by never letting it pass through to the fallback behavior.

Much of the complexity of this specification is designed around preventing such abuse. Without it, the API could consist of a single event. (Although that would make it ergonomically difficult for developers to coordinate on which component of their application should handle the close signal.) But with this constraint, we need an API surface such as the CloseWatcher() constructor which can note whether transient activation was present at construction time, as well as the close watcher stack to ensure that we remove at least one close watcher per close signal.

Concretely, the mechanism of creating a close watcher ensures that web developers can only create CloseWatcher instances, or call preventDefault() on cancel events, by attempting to consume user activation. If a CloseWatcher instance is created without transient activation, then after one "free" close watcher, any such close watcher is grouped together with the currently-top close watcher in the stack, so that both of them are closed by a single close signal. This gives similar protections to what browsers have in place today, where back button UI skips entries that were added without user activation. Similarly, if there hasn’t been any transient activation, the cancel event is not fired.

We do allow one "free" ungrouped CloseWatcher to be created, even without transient activation, to handle cases like session inactivity timeout dialogs, or urgent notifications of server-triggered events. The end result is that this specification expands the number of Android back button presses that a maximally-abusive page could require to escape from number of user activations + 1 to number of user activations + 2. (See the explainer for a full analysis.) We believe this tradeoff is worthwhile.

3.2. Privacy considerations

We believe the privacy impact of this API is minimal. The only information it gives about the user to the web developer is that a close signal has occurred, which is a very infrequent and coarse piece of user input.

In all cases we’re aware of today, such close signals are already detectable by web developers (e.g., by using keydown listeners on desktop or popstate listeners on Android). In theory, by correlating these existing events with the CloseWatcher's close event, a web developer could determine some information about the platform. (I.e., if they correlate with keydown events, the user is likely on desktop, or at least on a keyboard-attached mobile device.) This is similar to existing techniques which detect whether touch events or mouse events are fired, and user agents which want to emulate a different platform in order to mask the user’s choice might want to apply similar mitigation techniques for close watchers as they do for other platform-revealing events.