Full explainer available in the MSEdgeExplainers repo

Background

PWAs hosted within a user agent (UA) frame are able to declare which browser display mode best meets the needs of the application via the manifest file’s display member. Currently, there are 4 supported values and their behaviors on Chromium browsers are described below:

• fullscreen: All of the available display is used and no UA chrome is shown. This is implemented only for mobile devices running Android or iOS.
• standalone: The web app looks like a standalone application. The title bar includes the title of the application, a web app menu button, and caption control buttons (minimize, maximize/restore, close).
• minimal-ui: Similar to standalone, except it also contains a back and refresh button.
• browser: Currently, the same as minimal-ui

Problem

Developers want to create an immersive, native-like title bar for their desktop applications, but the display modes listed above do not support this. Instead, developers must shift content down below the reserved title bar area, which can create a cramped application space especially on portable devices with smaller screens.

Proposal

The solution proposed in this explainer is broken down into multiple parts:

1. A new display modifier option for the web app manifest - "caption-controls-overlay"
2. New APIs for developers to query the bounding rects and other states of the UA provided caption controls overlay which will overlay into the web content area through a new object on the window.navigator property called controlsOverlay
3. New CSS environment variables to define the left and right insets from the edges of the window: unsafe-area-top-inset-left and unsafe-area-top-inset-right
4. A standards-based way for developers to define system drag regions on their content

What does this mean? I’m not familiar with this.

Apparently I forgot to explain the most important concept, so thanks for calling that out!

The caption controls overlay is a notch-like overlay that would live in the upper-left or upper-right corner of the window and contains the caption control buttons (minimize, maximize/restore, close), a small draggable region, and any other controls required for privacy and security (e.g. the three-dot menu button in Chromium provides site security information and more).

Sorry, but I must be missing something still. What does you mean by caption here? To me, a caption is a bit of text that overlays a video with a transcription of the audio. But that doesn’t make sense to me in this context, so I assume you mean something else.

On Windows, the minimize, maximize/restore, and close buttons are referred to “caption controls” . On Mac, they’re referred to “window controls”.

Is this a widely used term outside of Microsoft? I’ve never heard that before, and the first page of a Google search for “caption controls” in quotes only returns results about captioning and subtitles.

If this is a Windows-specific term or a Microsoft-specific term, perhaps there’s a more general term that would better fit a web API that is not OS-specific.

It seems to be Microsoft/Windows specific. Maybe we can switch caption-controls-overlay to title-bar-controls-overlay?

That sounds good to me. I think I would have understood that right away. Thank you so much for taking the time to help me understand!

Title bars are also not universal. For example, titles are not included in the window frame on Chrome OS.

Also, including the name title bar makes it sound like titles are part of the overlay, when this would involve removing them if they exist.

How about window-controls-overlay?

In the case of ChromeOS, I would guess that the top of the window frame would still be called a “title bar” even if it doesn’t have a title in it, just because that is visually similar to a title bar. I’d be interested to hear what others would refer to it as.

That said, I do like windows-controls-overlay because it describes the main feature of the overlay: the window controls. The only concern that I have is that it could lead people to believe that it only contains the window controls, when in reality, it also contains a few other buttons/items.

We’ve updated the explainer title and content per feedback here and elsewhere:

Window Controls Overlay for Installed Desktop Web Apps

Background

PWAs hosted within a user agent (UA) frame are able to declare which browser display mode best meets the needs of the application via the manifest file’s display member . Currently, there are 4 supported values and their behaviors on Chromium browsers are described below:

• fullscreen : All of the available display is used and no UA chrome is shown. This is implemented only for mobile devices running Android or iOS.
• standalone : The web app looks like a standalone application. The title bar includes the title of the application, a web app menu button, and window control buttons (minimize, maximize/restore, close).
• minimal-ui : Similar to standalone , except it also contains a back and refresh button.
• browser : Currently, the same as minimal-ui

Problem

Developers want to create an immersive, native-like title bar for their desktop applications, but the display modes listed above do not support this. Instead, developers must shift content down below the reserved title bar area, which can create a cramped application space especially on portable devices with smaller screens.

Proposal

Add the option extend the app’s client area to cover the entire window–including the title bar area–and overlay the window control buttons (close, maximize/restore, minimize) on top of the client area. A developer then use this feature to create an installed desktop app with the appearance of a native title bar.

Hello WICG chairs. This API now has interest from Google (issue link below) and Microsoft. I would like to request to move the explainer to a WICG repo for incubation. Thanks!

cc. @marcosc, @cwilso, @yoavweiss, @travisleithead

Hi Amanda, I’ve set up http://github.com/WICG/display-override

Additionally, we have setup https://github.com/WICG/window-controls-overlay to directly incubate the feature proposed in the subject of this thread. Note that display-override is a building block for the window-controls-overlay feature, however, the scenarios and uses cases are sufficiently different to merit each to incubate in separate repos. Thanks!

Thanks @marcosc and @travisleithead for getting this set up!