From a46dd4f14fd377014b6d17687bae814d0243f506 Mon Sep 17 00:00:00 2001 From: Brad Triebwasser Date: Wed, 19 Oct 2022 15:40:37 -0700 Subject: [PATCH] Add Explainer. --- EXPLAINER.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 EXPLAINER.md diff --git a/EXPLAINER.md b/EXPLAINER.md new file mode 100644 index 0000000..e8300c6 --- /dev/null +++ b/EXPLAINER.md @@ -0,0 +1,132 @@ +# Multi-Screen Window Placement on the Web - Creating Fullscreen Popup Windows + +## Introduction + +This proposal introduces an additional way for web applications to initiate fullscreen experiences on multi-display configurations. The proposed enhancement would allow web applications to open a new window directly into fullscreen on a specified display with a single API call using the existing [window.open()](https://html.spec.whatwg.org/multipage/window-object.html#dom-open-dev) API. + +## Background + +[Multi-Screen Window Placement](https://github.com/webscreens/window-placement) +is a new permission-gated web platform API that provides web applications with +information about the device's connected screens, allows them to open and +position windows or request fullscreen on any of those screens. + +The HTML living standard specifies +[Tracking User Activation](https://html.spec.whatwg.org/multipage/interaction.html#tracking-user-activation), +to gate some web platform APIs on user interaction signals. The transient user +activation signal (e.g. from a mouse click) is required and consumed when web +application scripts open a popup window via `Window.open()`, and when they request +fullscreen via `Element.requestFullscreen()`. + +## Problem + +Web applications are limited in the ways that they can [Initiate Multi-Screen Experiences](https://github.com/w3c/window-placement/blob/main/EXPLAINER_initiating_multi_screen_experiences.md) across multi-display configurations. Specifically, opening a popup and transitioning the window to fullscreen requires two separate [user activations](https://html.spec.whatwg.org/multipage/interaction.html#tracking-user-activation), consumed by `window.open()` and `Element.requestFullscreen()` respectively. This results in a cumbersome user experience for web applications which utilize multiple displays. + +Multiple partners/early adopters of the API have specifically requested this enhancement (e.g. [window.open should support the 'fullscreen' option](https://github.com/w3c/window-placement/issues/7)) and it's considered a prerequisite to at least one other feature request (e.g. [Feature request: Fullscreen support on multiple screens](https://github.com/w3c/window-placement/issues/92)) + + +## Use Cases + +Some basic illustrative examples which may be achieved with this proposal are listed below: + +* Video streaming app launches a video directly to fullscreen on a secondary display. +* 3D modelling app allows user to launch a preview in fullscreen on a secondary display. + +Web applications may use this enhancement in conjunction with the existing [ability to enter fullscreen and open a popup from a single user gesture](https://w3c.github.io/window-placement/#usage-overview-initiate-multi-screen-experiences). By doing so, web applications can launch fullscreen experiences on the initial / primary display and a secondary display from a single user gesture. Some examples are listed below: + +* Financial app opens a fullscreen dashboard on the primary monitor and a fullscreen stock tracker window on a secondary display. +* Gaming app launches a fullscreen window on both primary and secondary displays for a continuous widescreen view. +* Virtual desktop app launches fullscreen windows on primary and secondary displays to mimic a remote monitor configuration. + + +## Goals + +The goal of this document is to outline the necessary spec changes that would permit web applications to open a fullscreen window on a secondary display. It also aims to explore abuse and other security / privacy considerations. Some specific goals are as follows: + +* Extend the `Window.open()` algorithm to change the behavior of the opened window based on parameters passed. +* Explore the behavior of user agents when the launched window exits fullscreen. + +The [Initiating Multi-Screen Experiences Explainer](https://github.com/w3c/window-placement/blob/main/EXPLAINER_initiating_multi_screen_experiences.md) covers some related goals (i.e. launching N fullscreen windows on N displays) not covered in this proposal. + +## Proposal + +Allow sites with the `window-placement` permission to open a fullscreen window on a secondary display from a single user gesture. When the device has multiple screens and `Window.open()` targets the secondary screen with an appropriate flag to create the window as fullscreen (via the `features` argument), the user agent should open the window as fullscreen on the display which contains the coordinates (`left`, `top`, `width`, `height`) of the new window. When the new window ultimately exits fullscreen, the window shall be restored as a popup style (bordered) window matching the coordinates originally passed to `Window.open()`. + + +### Example Code + +```js + const otherScreen = screenDetails.screens.find(s => s !== primaryScreen); + window.open(url, '_blank', `left=${otherScreen.availLeft},` + + `top=${otherScreen.availTop},` + + `width=${otherScreen.availWidth},` + + `height=${otherScreen.availHeight},` + + `fullscreen=true`); +``` + +### Spec Changes + +The spec does not contain an exhaustive list of valid features in the `features` argument, however, the spec does contain procedures for determining if a [popup window is requested](https://html.spec.whatwg.org/multipage/window-object.html#popup-window-is-requested), and the specific `tokenizedFeatures` to look for. Following this model, the spec shall be updated to define a similar algorithm for checking if a **fullscreen window** is requested. A fullscreen window must also first be considered a popup window and also have `left` and `top` set in `features`. `left` and `top` determine which display the window will go fullscreen on, and the position of the popup when fullscreen is exited. + +After [checking if a popup window is requested](https://html.spec.whatwg.org/multipage/window-object.html#popup-window-is-requested), add the following section: + +To **check if a fullscreen window is requested**, given *tokenizedFeatures*: + + +1. If *tokenizedFeatures* is empty, then return false. +2. Let *popup* be the result of [checking if a popup window is requested](https://html.spec.whatwg.org/multipage/window-object.html#popup-window-is-requested). +3. If *popup* is false, then return false. +4. If *tokenizedFeatures*["`left`"] and *tokenizedFeatures*["`top`"] do not [exist](https://infra.spec.whatwg.org/#map-exists), then return false. +7. Let *fullscreen* be the result of [checking if a window feature is set](https://html.spec.whatwg.org/multipage/window-object.html#window-feature-is-set), given *tokenizedFeatures*, "`fullscreen`", and false. +8. If *fullscreen* is false, then return false. +9. Let *permissionState* be [request permission to use](https://w3c.github.io/permissions/#dfn-request-permission-to-use) "`window-placement`". +10. If *permissionState* is not "[granted](https://w3c.github.io/permissions/#dom-permissionstate-granted)", then throw a "[NotAllowedError](https://webidl.spec.whatwg.org/#notallowederror)" [DOMException](https://webidl.spec.whatwg.org/#idl-DOMException). +11. Return true. + +### Open questions + +#### Feature detection + +There is no standard API for querying which features are supported in the [Widow.open()](https://html.spec.whatwg.org/multipage/window-object.html#dom-open-dev) `features` argument. There is no way for a web application to check that the user agent supports the `fullscreen` key in the `features` argument without calling the API and detecting if the resulting window is fullscreen (i.e. window boundary comparisons). + +The ability to detect supported keys of the `features` argument is out of scope for this proposal. + +#### Exiting fullscreen (Restoring bounds) + +The living standard algorithm for [exit fullscreen](https://fullscreen.spec.whatwg.org/#exit-fullscreen) does not specify the user agent's behavior of the restored window: + +``` +9. If resize is true, resize doc’s viewport to its "normal" dimensions. +``` + +It may be worth exploring an extension of the spec to specify that a window opened directly to fullscreen using this proposal, should be restored to the bounds originally specified in the (`left`, `top`, `width`, `height`). In the meantime, a user agent may decide how the window is restored. + + +#### Overlapping Fullscreen Windows / Invalid coordinates + +This proposal & spec change does not define the behavior of the user agent when the requested coordinates (`left`, `right`) overlap an existing (fullscreen) browser window. The intention of this proposal is for web applications to launch popups on secondary displays, however that may not always happen due to user / developer errors or defects. For example, a web application creating a fullscreen window on in a single display environment with an already fullscreen browser window. + +Each user agent may define their own behavior and security safeguards for these scenarios. For example pre-existing protections prevent placing popups over fullscreen: +* Chrome exits fullscreen (see + [ForSecurityDropFullscreen](https://source.chromium.org/chromium/chromium/src/+/main:content/public/browser/web_contents.h?q=ForSecurityDropFullscreen)) +* Firefox exits fullscreen +* Safari opens the popup in a separate fullscreen space + +## Security Considerations + +A notable security consideration stems from the fact that the web application may launch a fullscreen window on a display that the user is not looking at, since the [user activation](https://html.spec.whatwg.org/multipage/interaction.html#tracking-user-activation) (i.e. button click) may have occurred on another display which the user is focused on. The user may not notice the fullscreen window transition, nor the fullscreen bubble (e.g. Firefox's "\ is now full screen [Exit Full Screen (Esc)]" or Chrome's "Press [Esc] to exit full screen") which could allow for a malicious application to mimic other applications or the operating system without the user realizing that it is a browser window. + +This is partially mitigated by gating this feature on the "`window-placement`" permission. Users should only grant permissions for [powerful features](https://w3c.github.io/permissions/#dfn-powerful-feature) to web applications that they trust. + +This could also be mitigated further by having the user agent show the fullscreen bubble only when the user first interacts with the cross-display fullscreen window. In this scenario, there is a higher confidence that the user will see the fullscreen bubble. + +## Privacy Considerations + +This feature does not expose any information to sites, and there are no privacy considerations to note beyond those already documented in the Multi-Screen Window Placement [Privacy Considerations](https://www.w3.org/TR/window-placement/#privacy) section. The feature is gated behind the "`window-placement`" permission, so it does not expose any information outside what is already available from the API when permission is granted. + +## Alternatives Considered + + * Keeping the existing behavior. Web applications can create a popup, and then expand it's bounds to consume the entire display to mimic fullscreen content. + * This contains window borders and decorations not appropriate for some use cases. + * Allow a target-screen fullscreen request after opening a cross-screen popup + * This is less intuitive for the application developer and requires more complex changes to user activation signals which has a higher risk for misuse or abuse. \ No newline at end of file