Intent to Ship: Window Controls Overlay for Installed Desktop Web Apps

[Diego Gonzalez]

Contact emails

amb...@microsoft.com, luig...@microsoft.com, hat...@microsoft.com, c...@chromium.org

 

Explainer

https://github.com/WICG/window-controls-overlay/blob/master/explainer.md

 

Specification

https://wicg.github.io/window-controls-overlay/ 

 

Design docs

 

https://github.com/WICG/window-controls-overlay/blob/main/explainer.md

 

Summary

Window Controls Overlay allows a developer to create a custom title bar UX by extending the installed app’s client area. The client area now covers the entire window except for the window controls (close, maximize/restore, minimize), which are overlaid in their respective position. 

 

The web app developer is responsible for drawing and input-handling for the entire window except for the window controls overlay. This includes defining which area of the window is draggable as well, with a prefixed and non-prefixed version of a css property supported, as implemented in: crrev.com/c/3094474.

 

Intended uses for the Window Controls Overlay are creating seamless UX that can use the area that was reserved for the title bar before. Many modern applications include menus, search bars and other controls in the title bar, and this feature enables this on installed web apps.

 

Blink component

UI>Browser>WebAppInstalls

 

Search tags

PWA, web app, title bar, titlebar, customization, window controls

 

TAG review

https://github.com/w3ctag/design-reviews/issues/481

 

TAG review status

Resolution: satisfied

 

Risks

 

Interoperability and Compatibility

Given that Edge has interest in the feature, there would be at least one other browser that implements it. The feature involves additive changes (new web app manifest entry, new JS API, new CSS env variables) and modifications (changes to frame, new use of env(safe-area-inset-*), but no removals, so the compatibility risk is minimal.

 

Gecko: defer https://github.com/mozilla/standards-positions/issues/529 

 

WebKit: No signal https://lists.webkit.org/pipermail/webkit-dev/2021-May/031865.html 

 

Web developers: Positive

https://twitter.com/firt/status/1385238446046859268?s=20

https://twitter.com/AnaestheticsApp/status/1408727417330573314?s=20

https://twitter.com/bashik7/status/1385821988208275457?s=20

https://twitter.com/abraham/status/1385201046767738880?s=20

 

Ergonomics

The changes associated with this feature will only be enabled for PWAs that opt-in to it, so there are minimal risks posed to the browser as a whole. A PWA that opts-in to the feature should also have minimal ergonomics risk since the manifest already needs to be parsed on startup to determine the correct display mode in which the app should be launched, so adding one extra manifest check on startup should have minimal impact.

 

Activation

The activation risk is low since this feature includes all the tools needed to create an app that uses the full extent of the window: new UA-provided window controls overlay, JS APIs to query the size of the overlay, and CSS environment variables to layout content around the overlay.

 

Security

The major risk is that giving sites partial control over the top of the app window allows developers to spoof content in what was previously a trusted, UA-controlled region. To minimize the risk of spoofing, the app will open by default in “standalone” mode with a full width title bar, and the user can toggle window controls overlay on and off via a button in the title bar/overlay.

 

Debuggability

The feature itself can be easily debugged by installing the PWA. Since it is a visual feature on the window itself, it is easy to test. Nonetheless, making sure parsing the “display-override” mode and associated values correctly is desired, which should be incorporated into the application tab of devtools, where all the other manifest warnings are displayed. 

 

Is this feature fully tested by web-platform-tests?

3170531: dpwas: WPT Tests for window-controls-overlay | https://chromium-review.googlesource.com/c/chromium/src/+/3170531

 

Flag name

#enable-desktop-pwas-window-controls-overlay

 

Requires code in //chrome?

False

 

Tracking bug

https://bugs.chromium.org/p/chromium/issues/detail?id=937121

 

Launch bug

https://crbug.com/1108107

 

Sample links

 

https://amandabaker.github.io/pwa/explainer-example/index.html

 

Estimated milestones

OriginTrial desktop last	96
OriginTrial desktop first	93
Expected Release	97

 

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5741247866077184

 

Links to previous Intent discussions

Intent to prototype: https://groups.google.com/a/chromium.org/forum/#!msg/blink-dev/cper6nNLFRQ/hU91kfCWBQAJ

Intent to Experiment: https://groups.google.com/a/chromium.org/g/blink-dev/c/HNHbpxvrECA/m/JJoXKQI3BAAJ

 

This intent message was generated by Chrome Platform Status.

 

 

Regards,

 

Diego González-Zúñiga

PM, Microsoft Edge

 

 

[Yoav Weiss]

This is an exciting improvement to PWA parity with native apps! :) 

On Wed, Oct 20, 2021 at 10:49 PM 'Diego Gonzalez' via blink-dev <blin...@chromium.org> wrote:

Contact emails

amb...@microsoft.com, luig...@microsoft.com, hat...@microsoft.com, c...@chromium.org

 

Explainer

https://github.com/WICG/window-controls-overlay/blob/master/explainer.md

 

Specification

https://wicg.github.io/window-controls-overlay/ 

The spec looks like it could use some work. Beyond the editorial, it doesn't seem like it defines the novel concepts that it introduces, nor the relevant processing models.

What do we expect developers to do as a fallback in non-supporting browsers?  

 

Security

The major risk is that giving sites partial control over the top of the app window allows developers to spoof content in what was previously a trusted, UA-controlled region. To minimize the risk of spoofing, the app will open by default in “standalone” mode with a full width title bar, and the user can toggle window controls overlay on and off via a button in the title bar/overlay.

OK, so both the app and the user need to opt-in? 

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/VI1PR83MB041666BD26451656C388347CCCBE9%40VI1PR83MB0416.EURPRD83.prod.outlook.com.

[Thomas Steiner]

Any plans to move the ﹀ icon into the three dots menu? It looks a bit ugly. There is an experiment to move the puzzle piece into the three dots menu, too, so maybe this icon could be there, too? Maybe after the user has toggled it for the first time to not hurt discoverability of WCO (even further). 

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAL5BFfWDHDLWrOEuYFM6g8DOLK1%3DkTkGKdy-k4W5uiAZkoQEjw%40mail.gmail.com.

--

Thomas Steiner, PhD—Developer Advocate (https://blog.tomayac.com, https://twitter.com/tomayac)

Google Germany GmbH, ABC-Str. 19, 20354 Hamburg, Germany
Geschäftsführer: Paul Manicle, Halimah DeLaine Prado
Registergericht und -nummer: Hamburg, HRB 86891

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.3.2 (GNU/Linux)

iFy0uwAntT0bE3xtRa5AfeCheCkthAtTh3reSabiGbl0ck0fjumBl3DCharaCTersAttH3b0ttom.hTtPs://xKcd.cOm/1181/
-----END PGP SIGNATURE-----

[Alex Russell]

I think this is a great question, but somewhat out of scope for the Intent. Please ping your local design/security teams ;-)

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/VI1PR83MB041666BD26451656C388347CCCBE9%40VI1PR83MB0416.EURPRD83.prod.outlook.com.

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

[Yoav Weiss]

On Thursday, October 21, 2021 at 9:31:23 AM UTC+2 Yoav Weiss wrote:

This is an exciting improvement to PWA parity with native apps! :) 

On Wed, Oct 20, 2021 at 10:49 PM 'Diego Gonzalez' via blink-dev <blin...@chromium.org> wrote:

Contact emails

amb...@microsoft.com, luig...@microsoft.com, hat...@microsoft.com, c...@chromium.org

 

Explainer

https://github.com/WICG/window-controls-overlay/blob/master/explainer.md

 

Specification

https://wicg.github.io/window-controls-overlay/ 

The spec looks like it could use some work. Beyond the editorial, it doesn't seem like it defines the novel concepts that it introduces, nor the relevant processing models.

Let me expand on that a bit. The spec introduces a new concept of a "window overlay" without really creating it as a concept. 

What I expect an interoperable spec to define the concept with as much detail as possible without getting OS- or implementation-specific. 

(Just to draw an example of what I have in mind, if I had to make something up, I'd go with something like: "<dfn>Window overlay</dfn> is an interface element that the operating system uses consistently across applications to enable the user to perform certain action to control the application such as closing it, expanding it to full screen, etc. This UI element takes fixed dimensions....")

Then, once you have that concept defined, you can start building on it and define the processing of the different methods based on that.

I'll open issues with other suggestions.

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

[Diego González]

Hola Yoav,

We've gone through several iterations of the WCO spec reviewed by Joshua Bell from Google, and while we are still making changes to it, we believe it is in a much better state and want to resubmit for consideration of the approvals needed for I2S.  See the updated spec below:

https://wicg.github.io/window-controls-overlay/

--Diego

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

[Yoav Weiss]

Thanks Diego! The updates are a great improvement, but I suspect are not sufficient for an interoperable implementation. I left a couple of comments on the open issues.

[Diego González]

Hola Yoav, I am looking at making the amendments listed on the github issues. I will update soon with the changes. Thanks 

[Ajay Rahatekar]

cc: ajayra...@google.com

[Diego González]

Hola,

See the updated spec here: https://wicg.github.io/window-controls-overlay. 

Thanks

[Diego González]

the the new *new* spec update https://wicg.github.io/window-controls-overlay/

[Yoav Weiss]

This looks great! Thanks for following up on the spec work!!

I had a couple more questions upthread:

• What are developers expected to do in non-supporting browsers?
• Would the user need to opt-in to having web app control over their title bar?

[Diego González]

Hola Yoav, 

For non supported browsers there are 2 options: 

• env variables take the specified default value by developers (if devs enable WCO).
• The web app will open as it would in the browser, with a titlebar if installed (if devs don't enable WCO). 

  WCO is enabled by the end user. The user must enable the feature by toggling the chevron on the controls overlay. This is remembered on subsequent app launches.

--diego

[Diego González]

Hola Yoav,

I wanted to add that we implemented the concept of a display-override to control the fallback of display modes. For non supported browsers, developers can also specify the display-override and even if this is not supported it will default to the display value in the manifest file. 

[Yoav Weiss]

On Tuesday, November 30, 2021 at 6:48:07 PM UTC+1 Diego González wrote:

Hola Yoav,

I wanted to add that we implemented the concept of a display-override to control the fallback of display modes. For non supported browsers, developers can also specify the display-override and even if this is not supported it will default to the display value in the manifest file. 

On Monday, 29 November 2021 at 18:29:41 UTC Diego González wrote:

Hola Yoav, 

For non supported browsers there are 2 options: 

• env variables take the specified default value by developers (if devs enable WCO).

So IIUC developers are supposed to use the env variables with reasonable fallback values for non-supporting browsers? Is that advice captured/documented somewhere?  

• The web app will open as it would in the browser, with a titlebar if installed (if devs don't enable WCO). 

  WCO is enabled by the end user. The user must enable the feature by toggling the chevron on the controls overlay. This is remembered on subsequent app launches.

OK, so lack of WCO support by the browser and lack of user opt-in would look the same from the developer's perspective?

[Diego González]

YUC. 😉

If a developer has used the environmental variables and the web app gets installed in browser that does not support it (then it is a parallel universe because Firefox nor Safari nor other desktop browser supports this *kidding*) then they can specify reasonable fallback values because they value progressive enhancement and responsive design. I will add a note about this to the spec, if you think it is necessary. 

Lack of WCO support and lack of user opt in do not look the same. In a supported browser both the env variables and the JS object in navigator exist even if the feature is turned off. 

[Diego Gonzalez]

There is a PR waiting to be merged that adds a note about developers using reasonable fallbacks on unsupported browsers, I will let you know once it gets merged. 

[Diego González]

Just as a heads up, all concerns have been addressed and the latest version of the spec is in a state where I believe we are all happy with. Thanks for all the feedback and comments!

[Yoav Weiss]

LGTM1

Thanks for driving those discussions and making the spec interoperable in the process.

[Chris Harrelson]

LGTM2

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/a31d3e96-fb01-45c4-b979-2f04cfdb06fdn%40chromium.org.

[Mike West]

I believe @Mike Taylor had some questions around spelling decisions in the API in our last API owners meeting. Mike, did you have a chance to look into that more deeply?

-mike

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAOMQ%2Bw8bNbLih3qqn%2B%3DEAx%2B8TiLScqM7RuR9-C%3DjfmacHnDYcA%40mail.gmail.com.

[Mike Taylor]

I did, but ran out of time before sending an email last night. :)

I see that getBoundingClientRect was renamed to getTitleBarRect, would it make sense to update the boundingRect attribute on the geometry change event as well, or do you think boundingRect is still the right name?

[Diego González]

Hola Mike, 

That is a very valid point. We've renamed the boundingRect attribute to titlebarAreaRect to remove any ambiguity regarding the area being referenced. 

The change has now been merged. Thanks!

Diego

[Mike Taylor]

Great!

LGTM3

[Sonja Laurila]

Hey,

This feature has also been implemented for ChromeOS and I was wondering if it needs a separate I2S or if it should go with this same one?

Most of the WML implementation worked for CrOS already just by adding CrOS to the about flag definition and to the directive conditions, e.g. reading the CSS attributes etc. The missing parts of the CrOS implementation can be found on this CL: https://crrev.com/c/3204967/ (was later enabled for LaCrOS also: https://crrev.com/c/3240745). The implementation is fairly similar to the implementation for W&L. The only missing piece of the puzzle for CrOS atm is that it is still not included in runtime_enabled_features.json5.

So just to follow the processes, what would be the next steps to get the CrOS side ship as well? :)

Best regards,

Sonja Laurila

[Daniel Bratell]

I don't see our shipping decision as being limited to any particular platform, except that mobile was excluded by the "desktop web apps" title so you go ahead and ship for ChromeOS as well.

/Daniel

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/a94d9d91-9686-485c-bf83-8d490a427b4en%40chromium.org.