Document Picture-in-Picture Specification

1. Introduction

This section is non-normative.

There currently exists a Web API for putting an HTMLVideoElement into a Picture-in-Picture window (requestPictureInPicture()). This limits a website’s ability to provide a custom picture-in-picture experience (PiP). We want to expand upon that functionality by providing the website with a full Document on an always-on-top window.

This new window will be much like a blank same-origin window opened via the existing open() method on Window, with some minor differences:

• The PiP window will float on top of other windows.

• The PiP window will never outlive the opening window.

• The website cannot set the position of the PiP window.

• The PiP window cannot be navigated (any `window.history` or `window.location` calls that change to a new document will close the PiP window).

2. Dependencies

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

3. Security Considerations

3.1. Secure Context

The API is limited to [SECURE-CONTEXTS].

3.2. Spoofing

It is required that the user agent provides enough UI on the DocumentPictureInPicture window to prevent malicious websites from abusing the ability to float on top of other windows to spoof other websites or system UI.

3.2.1. Positioning

The user agent must prevent the website from setting the position of the window in order to prevent the website from purposefully positioning the window in a location that may trick a user into thinking it is part of another page’s UI. In particular, this means the moveTo() and moveBy() APIs must be disabled for document picture-in-picture windows.

3.2.2. Origin Visibility

It is required that the user agent makes it clear to the user which origin is controlling the DocumentPictureInPicture window at all times to ensure that the user is aware of where the content is coming from. For example, the user agent may display the origin of the website in a titlebar on the window.

3.2.3. Maximum size

The user agent should restrict the maximum size of the document picture-in-picture window to prevent the website from covering the screen with an always-on-top window and locking the user in the picture-in-picture window. This also helps prevent spoofing the user’s desktop.

3.2.4. Fullscreen

The user agent must prevent the document picture-in-picture window from entering fullscreen with the same reasoning as stated for the maximum size restriction. In particular, this means the requestFullscreen() API must be disabled for all elements in document picture-in-picture windows.

3.3. IFrames

This API is only available on a top-level traversable. However, the DocumentPictureInPicture Window itself may contain HTMLIFrameElements, even cross-origin HTMLIFrameElements.

4. Privacy Considerations

4.1. Fingerprinting

When a PiP window is closed and then later re-opened, it can be useful for the user agent to re-use size and location of the previous PiP window to provide a smoother user experience. However, it is recommended that the user agent does not re-use size/location across different origins as this may provide malicious websites an avenue for fingerprinting a user.

5. API

[Exposed=Window]
partial interface Window {
  [SameObject, SecureContext] readonly attribute DocumentPictureInPicture
    documentPictureInPicture;
};

[Exposed=Window, SecureContext]
interface DocumentPictureInPicture : EventTarget {
  [NewObject] Promise<Window> requestWindow(
    optional DocumentPictureInPictureOptions options = {});
  readonly attribute Window window;
  attribute EventHandler onenter;
};

dictionary DocumentPictureInPictureOptions {
  [EnforceRange] unsigned long long width = 0;
  [EnforceRange] unsigned long long height = 0;
  boolean disallowReturnToOpener = false;
  boolean preferInitialWindowPlacement = false;
};

[Exposed=Window, SecureContext]
interface DocumentPictureInPictureEvent : Event {
  constructor(DOMString type, DocumentPictureInPictureEventInit eventInitDict);
  [SameObject] readonly attribute Window window;
};

dictionary DocumentPictureInPictureEventInit : EventInit {
  required Window window;
};

enter

Fired on DocumentPictureInPicture when a PiP window is opened.

6. Concepts

6.1. Document Picture-in-Picture Support

Each user agent has a Document Picture-in-Picture Support boolean, whose value is implementation-defined (and might vary according to user preferences).

6.2. DocumentPictureInPicture Window

Each top-level traversable has an Is Document Picture-in-Picture boolean, whose value defaults to false, but can be set to true in the requestWindow() method steps.

6.3. Closing a Document Picture-in-Picture window

Merge this into definitely close once it has enough consensus.

Modify step 2 of definitely close, "If the result of checking if unloading is user-canceled for toUnload is not "continue", then return." to be:

2. If traversable’s Is Document Picture-in-Picture boolean is true, then skip this step. Otherwise, if the result of checking if unloading is user-canceled for toUnload is not "continue", then return.

6.4. Close any existing PiP windows

To close any existing picture-in-picture windows:

1. For each top-level traversable of the user agent’s top-level traversable set:

   1. If top-level traversable’s Is Document Picture-in-Picture boolean is true, then close top-level traversable.

   2. If top-level traversable’s active document’s pictureInPictureElement is not null, run the exit Picture-in-Picture algorithm with top-level traversable’s active document.

   3. For each navigable of top-level traversable’s active document’s descendant navigables:

      1. If navigable’s active document’s pictureInPictureElement is not null, run the exit Picture-in-Picture algorithm with navigable’s active document.

6.5. One PiP Window

Any top-level traversable must have at most one document picture-in-picture window open at a time. If a top-level traversable whose active window’s documentPictureInPicture API’s last-opened window is not null tries to open another document picture-in-picture window, the user agent must close the existing last-opened window as described in the requestWindow() method steps.

However, whether only one window is allowed in Picture-in-Picture mode across all top-level traversables is left to the implementation and the platform. As such, what happens when there is a Picture-in-Picture request while there is a top-level traversable whose Is Document Picture-in-Picture boolean is true or whose active document’s pictureInPictureElement is not null will be left as an implementation detail: the user agent could close any existing picture-in-picture windows or multiple Picture-in-Picture windows could be created.

6.6. Closing the PiP window when either the original or PiP document is destroyed

To close any associated Document Picture-in-Picture windows given a Document document:

1. Let navigable be document’s node navigable.

2. If navigable is not a top-level traversable, abort these steps.

3. If navigable’s Is Document Picture-in-Picture boolean is true, then close navigable and abort these steps.

4. Let win be navigable’s active window’s documentPictureInPicture API’s last-opened window.