diff --git a/EXPLAINER_additional_windowing_controls.md b/EXPLAINER_additional_windowing_controls.md new file mode 100644 index 0000000..a2c0202 --- /dev/null +++ b/EXPLAINER_additional_windowing_controls.md @@ -0,0 +1,346 @@ +# Explainer for Additional Windowing Controls + +## Introduction + +This proposal introduces additional ways for web applications to introspect and control their windows, to enable critical window management functionality on the web platform. + +The proposed enhancement would allow web applications to maximize, minimize, and restore their windows, control whether the window can be resized, and introspect the window state related to the mentioned controls, that is the window display state and ability to be resized by the user. + +The [window management permission](https://w3c.github.io/window-management/#api-permissions) will be required for the new JS APIs (window.maximize()/minimize()/restore()/setResizable(bool)). +The new CSS media features `display-state` and `resizable` are not gated behind a permission as they can follow the non-AWC API toggled states as well. + + +## Background + +[Virtual Desktop Infrastructure](https://en.wikipedia.org/wiki/Desktop_virtualization) (VDI) providers allow software running remotely on a host device to be displayed on a separate client device. For example, the VDI provider's cloud might run a text processor application, and present the user interface window within a client device’s desktop environment, as if that application were running locally. + +[Additional Explorations](https://github.com/w3c/window-management/blob/main/additional_explorations.md#extend-apis-to-control-window-state-display-modes-etc) of [Window Management](https://github.com/w3c/window-management) contained suggestions for incremental improvements to existing window management APIs. That helped inform this explainer, and contains more background. + +[Window Controls Overlay](https://wicg.github.io/window-controls-overlay/) offers new capabilities for web applications to control the area that would generally be occupied by the title bar in an installed web application running on a desktop environment. That specification also allows applications to [define draggable regions or content](https://wicg.github.io/window-controls-overlay/#defining-draggable-sections), which is highly relevant to this proposal. + +Demo app that ties in proposals from this doc https://awc-demo-4a08a808.web.app/ + + +## Problem and Use Cases + +VDI web clients have limited abilities to integrate remote application windows with the local desktop environment, which creates suboptimal experiences for their users. Currently, they can only present full disjoint remote desktop environments (e.g. in a local fullscreen window), or present individual remote applications in separate local windows with titlebar window controls that are inoperative, redundant, and confusing for users. + + +
Remote window presented within a local window
+ + +Several VDI clients, including Citrix and Omnissa, have reported that their users strongly desire an integrated experience as their work is increasingly happening both on local client and remote host devices. + +Unfortunately, the web platform offers no means for web applications to signal the user agent when users interact with remote application (or custom) window controls. This platform gap creates a disconnect between local and remote windows, and prevents web VDI clients from offering functionality expected by users. + +The missing capabilities also prevent a broader set of web applications from offering compelling window management experiences for their users. + + +## Proposal + +This proposal seeks to enable local web applications to convey a user's intended window control interactions with remote (or custom) window controls. Summary of the API proposals, which are generally gated by Window Management permission: + + + +* `await window.minimize()/maximize()/restore()` changes the window display state +* `display-state` CSS media feature yields the current window display state +* `await window.setResizable(bool)` sets whether the window is user-resizable +* `resizable` CSS media feature yields whether the window is user-resizable + +Windows that are not user-resizable prevent resizing by the user via keyboard shortcuts, mouse drag resize handles, window frame controls, and menus. Such windows do still allow resizing by Web APIs (e.g., `window.resizeTo()`, `window.maximize()`, and `element.requestFullscreen()`). + +Use cases explored here also rely upon a [parallel effort to standardize](https://github.com/w3c/csswg-drafts/issues/7017) the existing CSS property `-webkit-app-region/app-region`. + + +### Support custom and remote titlebar window dragging + +An [open proposal to standardize](https://github.com/w3c/csswg-drafts/issues/7017) the existing `-webkit-app-region/app-region `CSS property is valuable for [Window Controls Overlay](https://wicg.github.io/window-controls-overlay/) and for VDI client use cases explored here. This property allows web apps to specify web content areas (e.g. custom or remote application title bars) that can be used to drag the window within the local desktop environment. (ref. [Electron seamless titlebar tutorial](https://github.com/binaryfunt/electron-seamless-titlebar-tutorial)): + + +```html + +[window.getScreenDetails()](https://w3c.github.io/window-management/#api-extensions-to-window), [navigator.getBattery()](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/getBattery), and [navigator.requestMIDIAccess()](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMIDIAccess)
+ * Encapsulates permission-gated properties, methods, and event targets
+ * Provides live data that callers can cache a reference to
+ * CONs:
+ * Minor added complexity for callers
+ * Puts minimize()/maximize()/restore() in a different place than close(). (Although, close() is already different because it's sync)
+* Sync window.displayState interface access
+ * PROs:
+ * Precedent of [navigator.geolocation](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/geolocation) and [navigator.clipboard](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/clipboard)
+ * Encapsulates properties, methods, and event targets
+ * Provides live data that callers can cache a reference to
+ * CONs:
+ * Does not offer easy permission gating
+ * Puts minimize()/maximize()/restore() in a different place than close(). (Although, close() is already different because it's sync)
+
+
+### Extending app-region with minimize/maximize/restore/close types
+
+An alternative to the JS API would be to extend `app-region` CSS to support minimize/maximize/restore/close types. That lets a VDI simply set a region over each of the remote applications buttons that request the user agent to handle clicks in a particular way. Note: this is the old school windows hit testing approach (“I ask the window manager what is here where I clicked” - “minimize hit test”).
+
+
+
+* PROs:
+ * might be simpler than the JS API
+* CONs:
+ * might not work for all VDI’s use cases (user selecting a remote-app menu item like Window>Minimize would need a transient app-region and would be tricky; user pressing a remote-app-specific hotkey like Ctrl+M to minimize the remote window would be impossible)
+
+
+### Replacing window.setResizable() with manifest property and window.open() feature (static vs. dynamic resizable)
+
+The window resizable property could be set statically during window creation (via either manifest property or window.open() feature), but this doesn’t cover all of the VDI clients use-cases as the property could change dynamically during window life-time (since they display remote windows).
+
+
+### Introduction of window.onmove event to obviate the need for polling window positions
+
+A `move` event on `window` was initially suggested as a part of this proposal. It was rejected because of privacy concerns (see discussions [here](https://github.com/w3c/csswg-drafts/issues/7693) and [here](https://github.com/WebKit/standards-positions/issues/289)).
+
+## Security & Privacy Considerations
+
+JS APIs usage would be gated by:
+
+
+
+* Secure origins with the [Window Management permission](https://w3c.github.io/window-management/)
+* Consuming a user gesture for `window.minimize()/maximize()/restore()` APIs:
+ * To make `restore()` work with minimized windows (which can’t get a user gesture) we will extend the capability delegation API (i.e. `postMessage()` consumes activation in one window and transfers it to another window permitting it to `restore()`, even cross-origin)
+* `window.minimize()/maximize()/restore()` are limited to:
+ * Windows with ‘standalone’ or ‘minimal-ui’ [display-mode](https://www.w3.org/TR/mediaqueries-5/#display-mode), i.e. installed application windows, and origins running in their own window, whether installed or not, e.g. Chrome’s “Create shortcut…” with “Open as window” checked
+ * Popup windows created by script, i.e. `window.open()`
+
+Here are the most prevalent concerns raised by this API. Malicious sites may wish to:
+
+
+
+* minimize windows (abuse similar to pop-unders)
+* restore minimized windows or maximize ‘normal’ windows (to attempt click-jacking, show undesirable content, or block display of or access to other windows)
+* get window display state and resizable information (for fingerprinting)
+* observe concurrent window display state changes across site boundaries (for cross-site identity joining)
+
+It is valuable to also consider concerns raised by preexisting window control APIs, such as `window.open()`, `window.moveTo|resizeTo()`, `window.close()`, `window.screenX|screenY|outerWidth|outerHeight`, `element.requestFullscreen()`, and others, as those likely apply to this API surface too. In general, the threats associated with this API functionality (especially restore) are the same as that of [window management](https://w3c.github.io/window-management/). That is, if an app can open new windows or move and resize its existing windows anywhere on the device’s screens, then the ability to maximize, minimize, and restore its windows presents relatively little additional concern. It is worth noting that web apps today can [enter fullscreen (with a user gesture)](https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen) where they are given total control over the display.
+
+
+## References & acknowledgements
+
+### References
+
+[Additional Explorations of Window Placement on the Web](https://github.com/w3c/window-management/blob/main/additional_explorations.md#extend-apis-to-control-window-state-display-modes-etc) - Helped inform API shape, contains more background.
+
+[Draggable region (Frameless Window | Electron)](https://www.electronjs.org/docs/latest/api/frameless-window#draggable-region) - Electron apps use -webkit-app-region CSS property to specify draggable regions.
+
+[Electron seamless titlebar tutorial](https://github.com/binaryfunt/electron-seamless-titlebar-tutorial)
+
+* Electron tutorial on replacing the native title bar with a custom hand rolled one.
+* Creating a title bar and adding the window title, making it draggable, adding window control buttons, styling them, implementing logic behind them.
+
+### Acknowledgements
+
+Many thanks for valuable contributions, feedback, and advice from many folks, especially:
+
+- [@domenic](https://github.com/domenic)
+- [@ivansandrk](https://github.com/ivansandrk)
+- [@michaelwasserman](https://github.com/michaelwasserman)
+- [@sonkkeli](https://github.com/sonkkeli)
+- [@whateverpl](https://github.com/whateverpl)
diff --git a/image1.png b/image1.png
new file mode 100644
index 0000000..378103c
Binary files /dev/null and b/image1.png differ
diff --git a/index.bs b/index.bs
index 202bbd7..ff2ac7c 100644
--- a/index.bs
+++ b/index.bs
@@ -414,6 +414,20 @@ The advanced observable properties of a [=/screen=] are:
* The [=/screen=]'s designation as [=/primary=] or [=/secondary=]
* The [=/screen=]'s designation as [=/internal=] or [=/external=]
+
+## Window display state ## {#concept-window-display-state}
+
+
+A [=top-level browsing context=] has an associated display state, which can be one of:
+: normal
+:: The window is in a normal state (neither minimized, maximized, nor fullscreen).
+: minimized
+:: The window is minimized.
+: maximized
+:: The window is maximized.
+: fullscreen
+:: The window is in fullscreen mode.
+
# API # {#api}
@@ -485,6 +499,18 @@ The [[HTML]] standard defines the {{Window}} interface, which this specification
partial interface Window {
[SecureContext]
Promise+Name: display-state +Value: normal | minimized | maximized | fullscreen +For: @media +Type: discrete ++ +The '@media/display-state' media feature describes the window state in which the current [=browsing context=] is +currently being presented to the end user. In child browsing contexts, the [=display state=] must match that of +the [=top-level browsing context=]. + +This feature is primarily used to determine which [=display state=] has been applied by the host Operating System +to the user agent running the [=application context=]. + +
+Name: resizable +Value: true | false +For: @media +Type: discrete ++ +The '@media/resizable' media feature describes whether the window is user-resizable. + +