index.bs

<pre class=metadata>
Title: Window Management
Shortname: window-management
Abstract: This document defines a web platform API that allows script to query the device for information about its screens, and place content on specific screens.
Status: ED
TR: https://www.w3.org/TR/window-management/
URL: https://w3c.github.io/window-management/
Level: None
Editor: Joshua Bell, Google Inc. https://www.google.com/, jsbell@google.com, w3cid 61302
Editor: Mike Wasserman, Google Inc. https://www.google.com/, msw@google.com, w3cid 116970
Repository: w3c/window-management
Group: secondscreenwg
!Test Suite: <a href="https://github.com/web-platform-tests/wpt/tree/master/window-management">https://github.com/web-platform-tests/wpt/tree/master/window-management</a>
!Test Suite: <a href="https://github.com/web-platform-tests/wpt/tree/master/screen-details">https://github.com/web-platform-tests/wpt/tree/master/screen-details</a>
Logo: logo.svg
Favicon: logo.svg
Complain About: accidental-2119 yes, missing-example-ids yes
Markup Shorthands: css no, markdown yes
Assume Explicit For: yes
</pre>

<style>
.domintro::before {
    content: 'For web developers (non-normative)';
    text-transform: initial;
}
.domintro dt {
    font-family: Menlo, Consolas, "DejaVu Sans Mono", Monaco, monospace;

    padding-top: 0.5em;
    padding-bottom: 1em;
}
.domintro dt a {
    color: inherit; border-bottom-style: none;
}
.domintro dt code {
    font-size: inherit;
}
</style>

<pre class=anchors>
spec: css-values-4; urlPrefix: https://drafts.csswg.org/css-values-4/
    type: dfn; text: CSS pixel; url: px
spec: fingerprinting-guidance; urlPrefix: https://www.w3.org/TR/fingerprinting-guidance/
    type: dfn; text: passive fingerprinting; url: dfn-passive-fingerprinting
    type: dfn; text: active fingerprinting; url: dfn-active-fingerprinting
    type: dfn; text: cookie-like fingerprinting; url: dfn-cookie-like-fingerprinting
spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
    type: dfn; text: transient activation duration; url: transient-activation-duration
    type: dfn; text: last activation timestamp; url: last-activation-timestamp
spec: ecmascript; urlPrefix: https://tc39.es/ecma262/
    type: dfn; text: internal slot; url: sec-object-internal-methods-and-internal-slots
</pre>

<!-- ====================================================================== -->
# Introduction # {#introduction}
<!-- ====================================================================== -->

*This section is non-normative.*

Operating systems generally allow users to connect multiple screens to a single device and arrange them virtually to extend the overall visual workspace.

A variety of applications use platform tools to place their content in such multi-screen environments, but web application developers are limited by existing APIs, which were generally designed around the use of a single screen.

As multi-screen devices and applications become a more common and critical part of user experiences, it becomes more important to give web developers information and tools to leverage that expanded visual environment.

This specification incrementally extends the {{Window}}, {{Screen}}, and {{FullscreenOptions}} APIs, and introduces new {{ScreenDetails}} and {{ScreenDetailed}} interfaces. These changes allow web applications to offer compelling multi-screen experiences by placing content on specific screens.

<!-- ====================================================================== -->
## Motivating Use Cases ## {#motivations}
<!-- ====================================================================== -->

The aim of this specification is enable better experiences for web application users with multiple screens. Here are some use cases that inform the design:

* Slideshow app presents on a projector, shows speaker notes on a laptop screen.
* Financial app opens a dashboard of windows across multiple monitors.
* Medical app opens images (e.g. x-rays) on a high-resolution grayscale display.
* Creativity app shows secondary windows (e.g. palette) on a separate screen.
* Conference room app shows controls on a touch screen device and video on a TV.
* Multi-screen layouts in gaming, signage, artistic, and other types of apps.
* Site optimizes content and layout when a window spans multiple screens.

<!-- ====================================================================== -->
## Usage Overview ## {#usage-overview}
<!-- ====================================================================== -->

To support multi-screen experiences, the API allows web applications to:

1. Detect if the device has more than one screen
1. Request information required to place content on specific screens
1. Detect when a screen is added or removed
1. Detect when the current screen or an attribute thereof changes
1. Show an element fullscreen on a specific screen
1. Place a window on a specific screen
1. Initiate a multi-screen experience from a single transient user activation

<div class=example id=basic-example>

A basic example of the API usage is as follows:

```js
// Detect if the device has more than one screen.
if (window.screen.isExtended) {
  // Request information required to place content on specific screens.
  const screenDetails = await window.getScreenDetails();

  // Detect when a screen is added or removed.
  screenDetails.addEventListener('screenschange', onScreensChange);

  // Detect when the current \`ScreenDetailed\` or an attribute thereof changes.
  screenDetails.addEventListener('currentscreenchange', onCurrentScreenChange);

  // Find the primary screen, show some content fullscreen there.
  const primaryScreen = screenDetails.screens.find(s => s.isPrimary);
  document.documentElement.requestFullscreen({screen : primaryScreen});

  // Find a different screen, fill its available area with a new window.
  const otherScreen = screenDetails.screens.find(s => s !== primaryScreen);
  window.open(url, '_blank', \`left=${otherScreen.availLeft},\` +
                             \`top=${otherScreen.availTop},\` +
                             \`width=${otherScreen.availWidth},\` +
                             \`height=${otherScreen.availHeight}\`);
} else {
  // Detect when an attribute of the legacy \`Screen\` interface changes.
  window.screen.addEventListener('change', onScreenChange);

  // Arrange content within the traditional single-screen environment...
}
```

</div>

<!-- ====================================================================== -->
### Detect the presence of multiple screens ### {#usage-overview-screen-extended}
<!-- ====================================================================== -->

A principal question for supporting multi-screen experiences is whether the device has multiple screens that can be used when placing content. These screens can be built-in to the device (like a laptop display panel), attached to the device by wire (like a computer and monitor attached by an HDMI cable), connected to the device by other means (like Mac and iPad Sidecar functionality), or through display device virtualization. This is provided by the {{Screen/isExtended}} boolean, exposed to secure contexts without a permission prompt.

```js
if (screen.isExtended) {
  // Offer multi-screen controls for the user.
}
```

<!-- ====================================================================== -->
### Detect {{Screen}} attribute changes ### {#usage-overview-screen-changes}
<!-- ====================================================================== -->

Observing legacy {{Screen}} attribute changes is useful for adapting content, even on single-screen devices. Furthermore, observing {{Screen/isExtended}} is useful for detecting transitions between single-screen and multi-screen configurations. To avoid polling, {{Screen/change}} events are fired at the {{Screen}} object:

```js
screen.addEventListener('change', e => {
  // An attribute of the legacy \`Screen\` interface has changed.
});
```

<!-- ====================================================================== -->
### Request detailed screen information ### {#usage-overview-screen-details}
<!-- ====================================================================== -->

Detailed information about screens used by the device can be requested through the {{Window/getScreenDetails()}} method. This method may prompt the user for permission. The resulting {{ScreenDetails}} object lets developers enumerate screens, inspect their attributes, and listen for changes.

```js
try {
  // Request screen details and process the information immediately.
  const screenDetails = await window.getScreenDetails();
  processScreenDetails(screenDetails);

  // Process updated screen details when the set of screens change.
  screenDetails.onscreenschange = () => {
    processScreenDetails(screenDetails);
  };
} catch (err) {
  console.error(err);
  // Handle denied permission and other errors.
}

function processScreenDetails(screenDetails) {
  // Build a UI listing screens, using assumed helpers.
  clearScreenList();
  screenDetails.screens.forEach(screen => {
    addToScreenList({name: screen.label, screen: screen});
    // Process updated screen details when a particular screen's details change.
    screen.onchange = () => {
      processScreenDetails(screenDetails);
    };
  });
  selectCurrentInScreenList(screenDetails.currentScreen);
}
```

<!-- ====================================================================== -->
### Place fullscreen content on a specific screen ### {#usage-overview-place-fullscreen-content-on-a-specific-screen}
<!-- ====================================================================== -->

A common multi-screen use case is to present some content fullscreen on a specific screen. The screen may be selected interactively, or automatically selected based on screen attributes or prior user selections. A screen, once selected, can be passed to the {{Element/requestFullscreen()}} method.

```js
// Call an assumed helper that returns a selected \`ScreenDetailed\` instance.
const screenDetailed = getScreenForSlideshow();

// Request that a particular element be shown fullscreen on the selected screen.
slideshowElement.requestFullscreen({ screen: screenDetailed });
```

<!-- ====================================================================== -->
### Place windows on a specific screen ### {#usage-overview-place-windows-on-a-specific-screen}
<!-- ====================================================================== -->

Another common multi-screen use case is to place a window on a specific screen. This can be accomplished by using coordinates provided in the {{ScreenDetailed}} interface with existing {{Window/open()}} and {{Window/moveTo()}} methods.

```js
function openCenteredWindow(url, screenDetailed, w, h) {
  // Compute coordinates centering the window on the target screen.
  const l = screenDetailed.left + Math.round(screenDetailed.width - w) / 2;
  const t = screenDetailed.top + Math.round(screenDetailed.height - h) / 2;

  // Open the window with the requested dimensions.
  return window.open(url, '_blank', \`left=${l},top=${t},width=${w},height=${h}\`);
}
```

<!-- ====================================================================== -->
### Initiate multi-screen experiences ### {#usage-overview-initiate-multi-screen-experiences}
<!-- ====================================================================== -->

A commonly requested multi-screen use case is to initiate a compelling multi-screen experience from a single user activation. One specific proposed form is permitting a site to [[#usage-overview-place-fullscreen-content-on-a-specific-screen]] and [[#usage-overview-place-windows-on-a-specific-screen]] from a single user gesture. This can be accomplished by first requesting fullscreen on a specific screen of a multi-screen device, and then opening a popup window on another screen of the device, in a single event listener.

```js
initiateMultiScreenExperienceButton.addEventListener('click', async () => {
  // Find the primary screen, show some content fullscreen there.
  const primaryScreen = screenDetails.screens.find(s => s.isPrimary);
  await document.documentElement.requestFullscreen({screen : primaryScreen});

  // Find a different screen, fill its available area with a new window.
  const otherScreen = screenDetails.screens.find(s => s !== primaryScreen);
  window.open(url, '_blank', \`left=${otherScreen.availLeft},\` +
                             \`top=${otherScreen.availTop},\` +
                             \`width=${otherScreen.availWidth},\` +
                             \`height=${otherScreen.availHeight}\`);
});
```

<!-- ====================================================================== -->
# Concepts # {#concepts}
<!-- ====================================================================== -->

Concepts in this specification build upon those in the [CSSOM-View-1 Working Draft](https://www.w3.org/TR/cssom-view-1/), and the [CSSOM-View-1 Editor's Draft](https://drafts.csswg.org/cssom-view/), [[HTML]], and [[Fullscreen]].

<!-- ====================================================================== -->
## Screen ## {#concept-screen}
<!-- ====================================================================== -->

A device hosting the user agent has a single <dfn>screen</dfn> or multiple [=/screens=], which are used to display visual content. The set of [=/screens=] used by a device may change while a user agent is running, reflecting changes in the hardware or software configuration of the device.

Note: Some basic examples of screen configuration changes include connecting a television or projector to a laptop with an HDMI cable, closing the lid of a laptop to disable its built-in LCD panel, and changing the display resolution of a connected LCD computer monitor.

<div dfn-for="screen">

A [=/screen=] has a <dfn>color depth</dfn>, which is the [=pixel/color depth=] of the screen's pixels.

<div algorithm>

A [=/screen=] has a <dfn>device pixel ratio</dfn>, similar to {{Window}}'s {{Window/devicePixelRatio}}, which is the result of the following algorithm:

1. Let |CSS pixel size| be the size of a [=/CSS pixel=].

1. Let |device pixel size| be the vertical size of a [=screen/pixel=].

1. Return the result of dividing |CSS pixel size| by |device pixel size|.

</div>

A [=/screen=] has an <dfn>orientation</dfn>, which is described in [[screen-orientation]].

A [=/screen=] has a <dfn>label</dfn>, which is a string that meaningfully describes the screen to a user to help them identify and differentiate screens.

Note: The [=screen/label=] can be an arbitrary string selected by the user agent. It could describe the screen relative to the device, e.g. `"internal"` vs. `"external"`, it could include the dimensions, e.g. `"640×480"`, it could include hardware model information, e.g. `"Acme Telletube 1000x"` from [VESA E-EDID](https://en.wikipedia.org/wiki/Extended_Display_Identification_Data) data, it could include a distinguishing number, e.g. `"screen 1"` vs. `"screen 2"`, or all of the preceding. The label can be an empty string if underlying display details are unknown or the user agent chooses to hide that information. Applications can't assume that the label contains any specific information, such as the device type, model, dimensions, density, etc.


Advisement: While many screen attributes could be used for [=/active fingerprinting=], the strings used as [=screen/labels=] in particular should be considered carefully to minimize the uniqueness. For example, it would be a poor choice to include the serial number of the device.

Issue: Should [=screen/device pixel ratio=] include the [page-zoom](https://drafts.csswg.org/cssom-view-1/#page-zoom)?

</div>

<!-- ====================================================================== -->
## Screen pixel ## {#concept-screen-pixel}
<!-- ====================================================================== -->

<div dfn-for="screen">

A [=/screen=] has <dfn>pixels</dfn>, which are the smallest screen components that can be programmed directly. Each [=screen/pixel=] shows one color.

Note: On a liquid-crystal display (LCD), each pixel is made up of three components. Each component is a (red, green, blue) light with variable intensity. Reasoning about pixel components (subpixel rendering) is out of scope for this specification.

Note: Some screens can be configured to display content at a resolution that differs from the physical hardware's inherent composition; e.g. a monitor with a hardware resolution of 2560×1440 can be configured by the device to operate with a display resolution of 1920×1080.

A [=screen/pixel=] has a <dfn for="pixel">color depth</dfn>, which is the number of bits used to represent the colors it can display.

Note: Some popular rendering systems model [=screen/pixels=] as having a [=pixel/color depth=] of 24. These 3 groups of 8 bits represent the intensity of the (red, green, blue) subpixels of an LCD [=screen/pixel=].

</div>

<!-- ====================================================================== -->
## Screen area ## {#concept-screen-area}
<!-- ====================================================================== -->

<div dfn-for="screen">

A [=/screen=] has a <dfn>screen area</dfn>, which is a rectangular two-dimensional grid of [=screen/pixels=], used to present visual content from the operating system and client applications to the user. This corresponds to the [=/Web-exposed screen area=] of a particular [=/screen=].

A [=screen/screen area=] has a <dfn>width</dfn>, which is the number of [=screen/pixels=] along the horizontal dimension of the [=screen/screen area=]'s rectangular pixel grid.

A [=screen/screen area=] has a <dfn>height</dfn>, which is the number of [=screen/pixels=] along the vertical dimension of the [=screen/screen area=]'s rectangular pixel grid.

</div>

Note: The grid size is usually expressed as <[=screen/width=]>×<[=screen/height=]>. For example, a 1920×1080 screen area has a grid with a [=screen/width=] of 1920 pixels and a [=screen/height=] of 1080 pixels.

Note: As specified in [[CSSOM-VIEW-1#web-exposed-screen-information]], user agents may choose to hide information about the screen of the output device in order to protect the user’s privacy. In this case, the [=screen/screen area=] may be equal to that of the [viewport](https://drafts.csswg.org/css2/#viewport).

<!-- ====================================================================== -->
## Available screen area ## {#concept-available-screen-area}
<!-- ====================================================================== -->

<div dfn-for="screen">

A [=/screen=] has an <dfn>available screen area</dfn>, which is a rectangular subset of the [=screen/screen area=] where the operating system permits web application window placements. The rectangle's edges are parallel to the [=screen/screen area=] edges. This region does not include any portions of the [=screen/screen area=] that are reserved by the operating system for its own user interface elements, such as taskbars and menu bars. This equates to the [=/Web-exposed available screen area=] of a particular [=/screen=].

The <dfn>available width</dfn> of a [=/screen=] is the number of [=screen/pixels=] along the horizontal dimension of the [=screen/available screen area=]'s rectangular pixel grid.

The <dfn>available height</dfn> of a [=/screen=] is the number of [=screen/pixels=] along the vertical dimension of the [=screen/available screen area=]'s rectangular pixel grid.

</div>

<!-- ====================================================================== -->
## Virtual screen arrangement ## {#concept-virtual-screen-arrangement}
<!-- ====================================================================== -->

A device has a <dfn>virtual screen arrangement</dfn> that defines the relative placement of [=/screens=] that comprise the overall visual environment of the device. The arrangement is commonly composed on a two-dimensional plane extending in all directions, with (x, y)-coordinates that increase rightwards and downwards respectively from the <dfn>multi-screen origin</dfn>. The [=/multi-screen origin=] is an implementation-defined point that defines the (0, 0) coordinate of the [=/virtual screen arrangement=].

A common convention is to set the [=/multi-screen origin=] to the top-left of the [=/primary=] [=/screen=], but it can be any arbitrary point within the [=/virtual screen arrangement=]. Every [=/screen=]'s [=screen/screen area=] is a view onto a rectangular subset of the [=/virtual screen arrangement=].

This diagram shows some examples of how multiple [=/screens=] might be arranged within a [=/virtual screen arrangement=], along with some potential [=/multi-screen origins=]:

<img src="multi_screen_origin.svg" alt="Diagram showing various examples of screens and multi-screen origins" no-autosize>

Note: The [Second Screen Community Group](https://www.w3.org/community/webscreens/)'s [Form Factors Explained](https://webscreens.github.io/form-factors/) draft report explores related terminology and conceptual models.

<!-- ====================================================================== -->
## Screen position ## {#concept-screen-position}
<!-- ====================================================================== -->

A [=/screen=] has a <dfn for="screen">screen position</dfn> which is the [=screen/screen area=]'s (x, y)-coordinates in the [=/virtual screen arrangement=] relative to the [=/multi-screen origin=]. Coordinates may be negative, and are typically expressed as (<var ignore>x</var>, <var ignore>y</var>).

<!-- ====================================================================== -->
## Available screen position ## {#concept-available-screen-position}
<!-- ====================================================================== -->

A [=/screen=] has an <dfn for="screen">available screen position</dfn> which is the [=screen/available screen area=]'s (x, y)-coordinates in the [=/virtual screen arrangement=] relative to the [=/multi-screen origin=]. Coordinates may be negative, and are typically expressed as (<var ignore>x</var>, <var ignore>y</var>).

<!-- ====================================================================== -->
## Primary screen ## {#concept-primary-screen}
<!-- ====================================================================== -->

The device hosting the user agent has exactly one <dfn>primary</dfn> [=/screen=]. All the other [=/screens=] are considered <dfn>secondary</dfn>.

Note: The primary screen typically hosts the operating system's user interface for task management, such as the Windows taskbar and the macOS Dock.

A [=/screen=]'s designation as [=/primary=] or [=/secondary=] may change while the user agent is running.

Note: Most operating systems let the user choose the primary screen using a management user interface, such as the Windows Control Panel and the macOS Preferences application.

<!-- ====================================================================== -->
## Internal screen ## {#concept-internal-screen}
<!-- ====================================================================== -->

Each [=/screen=] may be designated as <dfn>internal</dfn> or <dfn>external</dfn>.

[=/External=] screens are manufactured separately from devices that provide their visual output. It is not unusual for an [=/external=] screen to be disconnected from one device and connected to a different device.

Note: As an example, a desktop computer might display its visual output on an [=/external=] screen connected by an HDMI cable. The HDMI cable can be connected or disconnected while the computer is in use, and the computer will adapt its visual environment to that hardware configuration change.

[=/Internal=] screens are usually attached to a device at manufacturing time. [=/Internal=] screens are not intended to be detached by users. However an [=/internal=] [=/screen=] can still be enabled or disabled while the user agent is running.

Note: As an example, a laptop might disable its [=/internal=] screen and input device when the lid is closed. The laptop can still be used in this configuration with an [=/external=] screen and input device. The disabled [=/internal=] screen can not be reported as a [=/screen=] used by the device while the lid is closed.

<!-- ====================================================================== -->
## Current screen ## {#concept-current-screen}
<!-- ====================================================================== -->

Scripts executing in a {{Window}} context can access the {{Window/screen}} attribute. That {{Screen}} object reflects properties of the <dfn>current screen</dfn>, which is the [=/screen=] that is currently presenting the window.

Note: On many operating systems, a window can be presented across multiple screens with different properties, or can be in a "hidden" state and not presented on any screen. Operating systems and user agents are assumed to define a canonical screen for a given {{Window}}, for example the screen with the largest area intersecting the window.

<!-- ====================================================================== -->
## Observable screen properties ## {#concept-observable-screen-properties}
<!-- ====================================================================== -->

The <dfn for="screen">basic observable properties</dfn> of a [=/screen=] are:

* The [=screen/width=] and [=screen/height=] of the [=screen/screen area=]
* The [=screen/available width=] and [=screen/available height=] of the [=screen/available screen area=]
* [=screen/color depth=]
* [=screen/orientation=]

The <dfn for="screen">advanced observable properties</dfn> of a [=/screen=] are:

* [=screen/screen position=]
* [=screen/available screen position=]
* [=screen/device pixel ratio=]
* [=screen/label=]
* The [=/screen=]'s designation as [=/primary=] or [=/secondary=]
* The [=/screen=]'s designation as [=/internal=] or [=/external=]

<!-- ====================================================================== -->
# API # {#api}
<!-- ====================================================================== -->

<!-- ====================================================================== -->
## Extensions to the {{Screen}} interface ## {#api-extensions-to-screen}
<!-- ====================================================================== -->

The [[CSSOM-VIEW-1|CSSOM View Module]] specification defines the {{Screen}} interface, which this specification extends:

<div class="domintro note">

    : |window| . |screen| . {{Screen/isExtended}}
    :: Returns `true` if the device's visual output extends over multiple screens.

    : |window| . |screen| . {{Screen/onchange}}
    :: Fired when the window's screen or attributes thereof change.

</div>

<xmp class=idl>
partial interface Screen /* : EventTarget */ {
  [SecureContext]
  readonly attribute boolean isExtended;

  [SecureContext]
  attribute EventHandler onchange;
};
</xmp>

Issue: Make {{Screen}} derive from {{EventTarget}} in [[CSSOM-VIEW-1#the-screen-interface]].

<!-- ====================================================================== -->
### {{Screen/isExtended}} attribute ### {#api-screen-isExtended-attribute}
<!-- ====================================================================== -->

<div algorithm>

The <dfn attribute for=Screen>isExtended</dfn> getter steps are:

1. If [=this=]'s [=relevant global object=]'s [=associated Document=] is not [=allowed to use=] the [=policy-controlled feature=] named "{{PermissionPolicy/window-management}}", return false and abort these steps.

1. Return true if the device has more than one [=/screen=], and false otherwise.

</div>

<!-- ====================================================================== -->
### {{Screen/onchange}} attribute ### {#api-screen-onchange-attribute}
<!-- ====================================================================== -->

The <dfn attribute for=Screen>onchange</dfn> attribute is an [=/event handler IDL attribute=] whose [=/event handler event type=] is {{Screen/change!!event}}.

When any [=screen/basic observable property=] of a {{Window}} |window|'s [=/current screen=] changes, [=/queue a global task=] on the [=/relevant global object=] of |window| using the [=/window placement task source=] to [=/fire an event=] named <dfn event for=Screen>`change`</dfn> at the {{Screen}} object referenced by |window|'s {{Window/screen}} attribute.

<!-- ====================================================================== -->
## Extensions to the {{Window}} interface ## {#api-extensions-to-window}
<!-- ====================================================================== -->

The [[HTML]] standard defines the {{Window}} interface, which this specification extends:

<div class="domintro note">

    : |window| . {{Window/getScreenDetails()}}
    :: Returns a promise that fulfills with a {{ScreenDetails}} object with information about the device's screens. The promise will be rejected if permission is denied.

</div>

<xmp class=idl>
partial interface Window {
  [SecureContext]
  Promise<ScreenDetails> getScreenDetails();
};
</xmp>

<!-- ====================================================================== -->
### {{Window/getScreenDetails()}} method ### {#api-window-getScreenDetails-method}
<!-- ====================================================================== -->

The {{Window/getScreenDetails()}} method completes asynchronously, queuing work on the <dfn>window placement task source</dfn>.

Instances of {{Window}} are created with an [=/internal slot=] named <dfn attribute for="Window">\[[screenDetails]]</dfn>, which is created with an initial value of `undefined`.

<div algorithm>

The <dfn method for=Window>getScreenDetails()</dfn> method steps are:

1. Let |promise| be [=/a new promise=].

1. If [=this=]'s [=relevant global object=]'s [=associated Document=] is not [=allowed to use=] the [=policy-controlled feature=] named "{{PermissionPolicy/window-management}}", then [=/reject=] |promise| with a {{"NotAllowedError"}} {{DOMException}} and abort these steps.

1. Run the following steps [=/in parallel=]:

    1. Let |permissionState| be [=/request permission to use=] "{{window-management}}".

    1. [=/Queue a global task=] on the [=/relevant global object=] of [=/this=] using the [=/window placement task source=] to run the following steps:

        1. If |permissionState| is "{{PermissionState/denied}}", then [=/reject=] |promise| with a {{"NotAllowedError"}} {{DOMException}} and abort these steps.

        1. If [=/this=].{{Window/[[screenDetails]]}} is `undefined`, then set [=/this=].{{Window/[[screenDetails]]}} to a new {{ScreenDetails}} object.

        1. [=/Resolve=] |promise| with [=/this=].{{Window/[[screenDetails]]}}.

1. Return |promise|.

</div>

<!-- ====================================================================== -->
### {{Window}} attribute and method definition changes ### {#api-window-attribute-and-method-definition-changes}
<!-- ====================================================================== -->

The following {{Window}} attributes and method definitions are updated to return and interpret values relative to the [=/multi-screen origin=]:

* {{Window/screenX}} and {{Window/screenLeft}} attributes must return the x-coordinate, relative to the [=/multi-screen origin=], of the left of the client window as number of [=/CSS pixels=], or zero if there is no such thing.
* {{Window/screenY}} and {{Window/screenTop}} attributes must return the y-coordinate, relative to the [=/multi-screen origin=], of the top of the client window as number of [=/CSS pixels=], or zero if there is no such thing.
* {{Window/moveTo()}} steps must interpret `x` and `y` arguments to be specified relative to the [=/multi-screen origin=].
* {{Window/open()}} steps must interpret `"left"` and `"top"` feature values to be specified relative to the [=/multi-screen origin=].


<!-- ====================================================================== -->
### {{Window/open()|Window.open()}} method definition changes ### {#api-window-open-method-definition-changes}
<!-- ====================================================================== -->

Instances of {{Window}} are created with an [=/internal slot=] named <dfn attribute for="Window">\[[targetScreenFullscreen]]</dfn>, which has a data model equivalent to [=/last activation timestamp=]. It corresponds to a {{DOMHighResTimeStamp}} value except for two cases: positive infinity indicates that the {{Window}} has never been activated, while negative infinity indicates that a user activation-gated API (see [[HTML#user-activation-gated-apis]]) has [=/consume user activation|consumed=] the last user activation of the {{Window}}. The initial value is positive infinity.

The {{Window/open()|Window.open()}} method steps, and the steps of methods invoked therein, are updated to optionally:
1. Waive the [=/transient activation=] state requirement when the [=/current high resolution time=] of the [=/relevant global object=] is greater than or equal to [=/this=].{{Window/[[targetScreenFullscreen]]}}, and less than [=/this=].{{Window/[[targetScreenFullscreen]]}} plus the [=/transient activation duration=].
1. Set [=/this=].{{Window/[[targetScreenFullscreen]]}} to negative infinity immediately after following the steps to [=/consume user activation=].

<!-- ====================================================================== -->
## {{ScreenDetails}} interface ## {#api-screendetails-interface}
<!-- ====================================================================== -->

<div class="domintro note">

    : |screenDetails| . {{ScreenDetails/screens}}
    :: Returns an array of {{ScreenDetailed}} objects that describe each of the screens.

    : |screenDetails| . {{ScreenDetails/currentScreen}}
    :: Returns a {{ScreenDetailed}} object that describes the [=/current screen=]. This object describes the same [=/screen=] as {{Window}}.{{Window/screen}}, but provides a superset of the information.

    : |screenDetails| . {{ScreenDetails/onscreenschange}}
    :: Fired when the set of [=/screens=] changes; i.e. when a [=/screen=] is added or removed.

    : |screenDetails| . {{ScreenDetails/oncurrentscreenchange}}
    :: Fired when the [=/current screen=] or an attribute thereof changes; i.e. when the window moves to another [=/screen=], or a property of the [=/current screen=] changes.

</div>

<xmp class=idl>
[Exposed=Window, SecureContext]
interface ScreenDetails : EventTarget {
  readonly attribute FrozenArray<ScreenDetailed> screens;
  readonly attribute ScreenDetailed currentScreen;

  attribute EventHandler onscreenschange;
  attribute EventHandler oncurrentscreenchange;
};
</xmp>

<!-- ====================================================================== -->
### {{ScreenDetails/screens}} attribute ### {#api-screendetails-screens-attribute}
<!-- ====================================================================== -->

<div algorithm>

The <dfn attribute for=ScreenDetails>screens</dfn> getter steps are:

1. Let |screens| be a new [=/list=].

1. For each |screen| of the device's [=/screens=]:

    1. Let |a| be the {{ScreenDetailed}} object describing |screen|.

    1. [=list/Append=] |a| to |screens|.

1. Return the result of [=list/sorting=] |screens| in ascending order with the [=/screen ordering=] algorithm.

</div>

<div algorithm>

The <dfn>screen ordering</dfn> algorithm defines a [=/screen=] |a| as less than a [=/screen=] |b| if the following steps return true:

1. If |a|'s [=screen/screen position=] x-coordinate is less than |b|'s [=screen/screen position=] x-coordinate, then return true.
1. If |b|'s [=screen/screen position=] x-coordinate is less than |a|'s [=screen/screen position=] x-coordinate, then return false.
1. If |a|'s [=screen/screen position=] y-coordinate is less than |b|'s [=screen/screen position=] y-coordinate, then return true.
1. Otherwise, return false.

</div>

<!-- ====================================================================== -->
### {{ScreenDetails/currentScreen}} attribute ### {#api-screendetails-currentscreen-attribute}
<!-- ====================================================================== -->

The <dfn attribute for=ScreenDetails>currentScreen</dfn> getter steps are to return the {{ScreenDetailed}} object in {{ScreenDetails/screens}} representing the [=/current screen=] of the {{Window}} object associated with [=/this=].

Note: Which exact {{ScreenDetailed}} object in {{ScreenDetails/screens}} represents the [=/current screen=] of a {{Window}} is assumed to be defined by operating systems and user agents. This corresponds with {{Window}}.{{Window/screen}}, the canonical screen for a given window, for example the screen with the largest area intersecting the window.

Note: {{ScreenDetails/currentScreen}} is guaranteed to be `===` comparable with one of the entries in {{ScreenDetails/screens}}, to facilitate such comparisons, e.g. `screenDetails.screens.find(s => s !== screenDetails.currentScreen);`. That precludes {{ScreenDetails/currentScreen}} from being marked `[SameObject]`. Relatedly, {{ScreenDetailed/change!!event}} event listeners added to {{ScreenDetails/currentScreen}} will only be notified of changes for that specific [=/screen=], while {{ScreenDetails/currentscreenchange!!event}} event listeners will be notified of changes for whichever [=/screen=] happens to be the window's [=/current screen=], i.e. after the window moves from one [=/screen=] to another.

<!-- ====================================================================== -->
### {{ScreenDetails/onscreenschange}} attribute ### {#api-screendetails-onscreenschange-attribute}
<!-- ====================================================================== -->

The <dfn attribute for=ScreenDetails>onscreenschange</dfn> attribute is an [=/event handler IDL attribute=] whose [=/event handler event type=] is {{ScreenDetails/screenschange!!event}}.

When the set of {{ScreenDetails/screens}} of a {{ScreenDetails}} object |screenDetails| changes, [=/queue a global task=] on the [=/relevant global object=] of |screenDetails| using the [=/window placement task source=] to [=/fire an event=] named <dfn event for=ScreenDetails>`screenschange`</dfn> at |screenDetails|.

<!-- ====================================================================== -->
### {{ScreenDetails/oncurrentscreenchange}} attribute ### {#api-screendetails-oncurrentscreenchange-attribute}
<!-- ====================================================================== -->

The <dfn attribute for=ScreenDetails>oncurrentscreenchange</dfn> attribute is an [=/event handler IDL attribute=] whose [=/event handler event type=] is {{ScreenDetails/currentscreenchange!!event}}.

When the [=/current screen=] of a {{Window}} |window| changes from one [=/screen=] to another (e.g. the {{Window}} has been moved to a different display), or when any [=screen/basic observable property=] or [=screen/advanced observable property=] of the [=/current screen=] of |window| changes, [=/queue a global task=] on the [=/relevant global object=] of |window| using the [=/window placement task source=] to [=/fire an event=] named <dfn event for=ScreenDetails>`currentscreenchange`</dfn> at the {{ScreenDetails}} object stored in |window|'s internal slot {{Window/[[screenDetails]]}}.

<!-- ====================================================================== -->
## The {{ScreenDetailed}} interface ## {#api-screendetailed-interface}
<!-- ====================================================================== -->

A {{ScreenDetailed}} object represents a [=/screen=].

<div class="domintro note">

  : |screenDetailed| . {{ScreenDetailed/availLeft}}
  :: Returns the distance from the [=/multi-screen origin=] to the left edge of the available screen area.

  : |screenDetailed| . {{ScreenDetailed/availTop}}
  :: Returns the distance from the [=/multi-screen origin=] to the top edge of the available screen area.

  : |screenDetailed| . {{ScreenDetailed/left}}
  :: Returns the distance from the [=/multi-screen origin=] to the left edge of the screen area.

  : |screenDetailed| . {{ScreenDetailed/top}}
  :: Returns the distance from the [=/multi-screen origin=] to the top edge of the screen area.

  : |screenDetailed| . {{ScreenDetailed/isPrimary}}
  :: Returns whether this screen is designated as the 'primary' screen by the OS (otherwise it is a 'secondary' screen).

  : |screenDetailed| . {{ScreenDetailed/isInternal}}
  :: Returns whether this screen is an 'internal' panel built into the device, like a laptop display (otherwise it is 'external', like a wired monitor).

  : |screenDetailed| . {{ScreenDetailed/devicePixelRatio}}
  :: Returns the ratio between physical and logical pixels.

  : |screenDetailed| . {{ScreenDetailed/label}}
  :: A user-friendly label for the screen, determined by the user agent and OS.

</div>

<xmp class=idl>
[Exposed=Window, SecureContext]
interface ScreenDetailed : Screen {
  readonly attribute long availLeft;
  readonly attribute long availTop;
  readonly attribute long left;
  readonly attribute long top;
  readonly attribute boolean isPrimary;
  readonly attribute boolean isInternal;
  readonly attribute float devicePixelRatio;
  readonly attribute DOMString label;
};
</xmp>

The <dfn attribute for=ScreenDetailed>availLeft</dfn> getter steps are to return the x-coordinate of the [=screen/available screen position=] of [=/this=] [=/screen=].

The <dfn attribute for=ScreenDetailed>availTop</dfn> getter steps are to return the y-coordinate of the [=screen/available screen position=] of [=/this=] [=/screen=].

The <dfn attribute for=ScreenDetailed>left</dfn> getter steps are to return the x-coordinate of the [=screen/screen position=] of [=/this=] [=/screen=].

The <dfn attribute for=ScreenDetailed>top</dfn> getter steps are to return the y-coordinate of the [=screen/screen position=] of [=/this=] [=/screen=].

The <dfn attribute for=ScreenDetailed>isPrimary</dfn> getter steps are to return true if [=/this=] [=/screen=] is the [=/primary=] [=/screen=], or false otherwise.

The <dfn attribute for=ScreenDetailed>isInternal</dfn> getter steps are to return true if [=/this=] [=/screen=] is [=/internal=], or false otherwise.

The <dfn attribute for=ScreenDetailed>devicePixelRatio</dfn> getter steps are to return the [=screen/device pixel ratio=] of [=/this=] [=/screen=].

The <dfn attribute for=ScreenDetailed>label</dfn> getter steps are to return the [=screen/label=] of [=/this=] [=/screen=].

<!-- ====================================================================== -->
### {{ScreenDetailed/onchange}} attribute ### {#api-screendetailed-onchange-attribute}
<!-- ====================================================================== -->

The <dfn attribute for=ScreenDetailed>onchange</dfn> attribute is the {{Screen/onchange}} attribute inherited from {{Screen}}.

When any [=screen/basic observable property=] or [=screen/advanced observable property=] of a [=/screen=] represented by a {{ScreenDetailed}} object |screenDetailed| changes, [=/queue a global task=] on the [=/relevant global object=] of |screenDetailed| using the [=/window placement task source=] to [=/fire an event=] named <dfn event for=ScreenDetailed>`change`</dfn> at |screenDetailed|.

<!-- ====================================================================== -->
## Extensions to {{FullscreenOptions}} ## {#api-extensions-to-fullscreen-options}
<!-- ====================================================================== -->

<div class="domintro note">

    : <var ignore>fullscreenOptions</var> . {{FullscreenOptions/screen}}
    :: Specifies a [=/screen=] for element fullscreen requests.

</div>

<xmp class=idl>
partial dictionary FullscreenOptions {
  ScreenDetailed screen;
};
</xmp>

The optional {{FullscreenOptions}} <dfn dict-member for=FullscreenOptions>screen</dfn> member indicates an application preference to display the element fullscreen on a particular [=/screen=]. User agents are always free to honor user preference over that of the application. The default value `undefined` indicates no application preference.

<!-- ====================================================================== -->
### {{Element/requestFullscreen|Element.requestFullscreen()}} method definition changes ### {#api-element-requestfullscreen-method-definition-changes}
<!-- ====================================================================== -->

The {{Element/requestFullscreen|Element.requestFullscreen()}} method steps are updated to optionally:
1. Take `options`["{{FullscreenOptions/screen}}"] into account when moving and resizing  `pendingDoc`’s [=/top-level browsing context=]’s [=navigable/active document=]’s viewport. The viewport may be moved to the specified [=/screen=] as part of this modified method step.
1. Set the [=/this=].{{Window/[[targetScreenFullscreen]]}} internal slot to the [=/current high resolution time=] if `options`["{{FullscreenOptions/screen}}"] specifies a recognized {{ScreenDetailed}} object with a value of true for {{Screen/isExtended}}.

<!-- ====================================================================== -->
## Permission API Integration ## {#api-permission-api-integration}
<!-- ====================================================================== -->

This specification defines a [=/default powerful feature=] that is identified by the [=powerful feature/name=] "<dfn export permission>window-management</dfn>".

The [[permissions]] API provides a uniform way for websites to query the state of their permissions.

Note: Previously published versions of this document used the permission name `"window-placement"`. User agents should carefully migrate to the updated permission string: "{{window-management}}". See [#114](https://github.com/w3c/window-management/issues/114).

Issue: Add {{window-management}} to [[permissions]] registry.

Issue: Define behavior of cached objects and method steps when the permission is revoked. (See [#80](https://github.com/w3c/window-management/issues/80))

<!-- ====================================================================== -->
## Permission Policy integration ## {#api-permission-policy-integration}
<!-- ====================================================================== -->

This specification defines a [=/policy-controlled feature=] identified by the string <dfn for=PermissionPolicy enum-value>"window-management"</dfn>, that controls whether {{Screen/isExtended}}, {{Window/getScreenDetails}}, and dependent functionality may be used. The [=policy-controlled feature/default allowlist=] for this feature is `'self'`. See [[permissions-policy]] and its list of [Experimental Features](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md#experimental-features).

Note: A [=/document=]’s permissions policy determines whether any content in that document is allowed to obtain a meaningful value from {{Screen/isExtended}}, access {{ScreenDetails}}, or place content on specific screens. If disabled, {{Screen/isExtended}} will return false, promises returned by {{Window/getScreenDetails}} will be rejected, and requests to place content on specific screens will be clamped to the [=/current screen=].

Issue: Move {{PermissionPolicy/window-management}} to [Proposed](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md#proposed-features) or [Standardized](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md#proposed-features) feature lists when appropriate.

<!-- ====================================================================== -->
# Security Considerations # {#security}
<!-- ====================================================================== -->

This specification enables sites to place content on specific screens, which may pose limited new security risks:
1. Sites may attempt to prominently display sensitive content on unexpected screens
1. Sites may attempt to surreptitiously display undesirable content on less conspicuous screens, for example:
  1. Sites may attempt to spoof the OS, browser, or other sites for phishing attacks, by drawing the user's attention to a particular screen, and use interaction signals there to show deceptive content on another screen that is less closely observed
1. Sites may attempt to otherwise place content on specific screens to act in deceptive, abusive, or annoying manners

To help mitigate such risks, cross-screen placement capabilities require express permission in secure contexts, and are subject to [[permissions-policy]], which prevent third-party access by default.

User agents can detect cross-screen placement requests, and intervene to protect users from potential abuse. For example, user agents may present prominent security surfaces when sites place content on another screen, or when windows gain user attention after cross-screen placement. Additionally, cross-screen placement requests may be denied or clamped to the [=/current screen=], matching pre-existing behavior of some user agents.

Other points to note:
- Some user agents already do not constrain window placement requests to the [=/current screen=]; they interpret {{Window/open()}} and {{Window/moveTo()}} coordinates as relative to the [=/multi-screen origin=], and honor requests to place windows on screens other than the [=/current screen=].
- Transient user activation is typically already required for {{Element/requestFullscreen()}} and {{Window/open()}}, but not for {{Window/moveTo()}}, {{Window/moveBy()}}, {{Window/resizeTo()}}, nor {{Window/resizeBy()}}.
- Placing content on a screen other than the [=/current screen=] is unlikely to create additional clickjacking risk for users, since the user's cursor or finger is likely to be co-located with the [=/current screen=], not on a separate screen.
- Gating legacy placement capabilities on the specified permission may be feasible.

See the following additional explorations of security considerations:
- [W3C Security and Privacy Self-Review Questionnaire for the overall API](https://github.com/w3c/window-management/blob/main/security_and_privacy.md)
- ["Privacy & Security" in the Explainer for the overall API](https://github.com/w3c/window-management/blob/main/EXPLAINER.md#privacy--security)
- [W3C Security and Privacy Self-Review Questionnaire for "Initiating Multi-Screen Experiences"](https://github.com/w3c/window-management/blob/main/security_and_privacy_initiating_multi_screen_experiences.md)
- ["Security Considerations" in the Explainer for "Initiating Multi-Screen Experiences"](https://github.com/w3c/window-management/blob/main/EXPLAINER_initiating_multi_screen_experiences.md#security-considerations)

<!-- ====================================================================== -->
# Privacy Considerations # {#privacy}
<!-- ====================================================================== -->

This specification exposes new information to sites about screens connected to the device, which may pose limited new privacy risks. This additional information increases the [fingerprinting](https://w3c.github.io/fingerprinting-guidance/) surface of devices, especially those with atypical screen configurations.

To help mitigate such risks, the new information is reduced to the minimum needed for common placement use cases, most access requires express permission in secure contexts, and is subject to [[permissions-policy]], which prevents third-party access by default. The list of screens exposed has a defined order to reduce interoperability issues and mitigate fingerprinting. User agents can generally measure and otherwise intervene when sites request any new information.

The `Screen.isExtended` boolean is exposed without explicit permission checks, as this minimal single bit of information supports some critical features for which a permission prompt would be obtrusive (e.g. show/hide multi-screen UI entry points like “Show on another screen”), and helps avoid unnecessarily prompting single-screen users for inapplicable information and capabilities. This generally follows a TAG design principle for device enumeration (see [[DESIGN-PRINCIPLES#device-enumeration]]).

Many user agents already effectively expose the presence of multiple screens to windows located on secondary screens, where `window.screen.availLeft|Top` >> 0. Script access of this bit is a detectable [=/active fingerprinting=] signal, which may be observed and blocked by the user agent. Additionally, user agents that do not constrain unpermissioned window placement requests to the [=/current screen=] allow adversaries to attempt programmatic placement on other screens, at which point information about that `window.screen` is exposed.

The new `Screen.onchange` events pose a slight risk by making [ephemeral fingerprinting](https://github.com/asankah/ephemeral-fingerprinting) easier, but scripts can already achieve the same result by polling for changes to `window.screen`. This risk could be partially mitigated by delaying event dispatch for hidden documents until such documents are no longer hidden.

Alternative API shapes giving less power to sites were considered, but offer poor experiences for users and developers (e.g. prompting users to pick a screen, requiring declarative screen rankings from developers). Few, if any, alternatives exist for non-fullscreen placement of app windows on any connected screen. The specified API shape seems like the most natural extension of existing APIs to support a more complete multi-screen environment. Future work may include ways to query more limited multi-screen information, to let sites voluntarily minimize their information exposure.

The specified API design enables user agents to selectively expose screens using novel access models, for example limiting screen information and placement capabilities pertaining to screens indicated by the user.

Other points to note:
- Gating legacy screen and window information on the specified permission may be feasible.

See the following additional explorations of privacy considerations:
- [W3C Security and Privacy Self-Review Questionnaire for the overall API](https://github.com/w3c/window-management/blob/main/security_and_privacy.md)
- ["Privacy & Security" in the Explainer for the overall API](https://github.com/w3c/window-management/blob/main/EXPLAINER.md#privacy--security)
- [W3C Security and Privacy Self-Review Questionnaire for "Initiating Multi-Screen Experiences"](https://github.com/w3c/window-management/blob/main/security_and_privacy_initiating_multi_screen_experiences.md)

<!-- ====================================================================== -->
# Accessibility Considerations # {#a11y}
<!-- ====================================================================== -->

This specification enables sites to place content on specific screens, which may pose limited new accessibility risks. The visual presentation, non-visual rendering, and effect of assistive technologies on the content itself is not commonly substantially influenced by the placement of content on one screen or another. Still, existing accessibility risks of programmatic content placement may be exacerbated by the expanded areas over which content may be placed. Existing accessibility considerations regarding [=/default powerful feature=] permission models, prompting methods, and permission-related UIs, are equally pertinent to this particular specification's permission.

There are no documented accessibility considerations pertaining to the structured screen information (and accessibility features thereof) exposed by the API at this time.

<!-- ====================================================================== -->
# Internationalization Considerations # {#i18n}
<!-- ====================================================================== -->

There are no documented internationalization considerations at this time.

<!-- ====================================================================== -->
# Acknowledgements # {#acknowledgements}
<!-- ====================================================================== -->

Many thanks to<!--
-->
Adrienne Walker,
Anssi Kostiainen,
Chris Terefinko,
Domenic Denicola,
Jonathan Garbee,
Kenneth Rohde Christiansen,
L. David Baron,
Lukasz Olejnik,
Marijn Kruisselbrink,
Matt Giuca,
Michael Ketting,
Nadav Sinai,
Peter Linss,
Reilly Grant,
Staphany Park,
Theresa O'Connor,
Thomas Nattestad,
Thomas Steiner, and
Victor Costan
<!--
-->for helping craft this specification.

Issue: Ensure we didn't forget anyone!

Special thanks to Tab Atkins, Jr. for creating and maintaining [Bikeshed](https://github.com/speced/bikeshed), the specification authoring tool used to create this document, and for his general authoring advice.