ChromeOS APIs for Isolated Web Apps

The chromeos attribute exposes ChromeOS-specific APIs. This attribute must return null if the current context is not allowlisted to use any of ChromeOS IWA APIs.

The isolatedWebApp attribute exposes APIs specific to Isolated Web Apps. This attribute must return null if the current context is not an IWA or not allowlisted to use the ChromeOS IWA APIs.

Since this API allows changing the visible shape of the window, it could be used to create invisible or extremely small windows to perform malicious actions without the user's knowledge. To mitigate this:

• Input validation enforces a minimum size for the shape.
• The API is restricted to allowlisted Isolated Web Apps.
• The user must grant the window-management permission.

The coordinates and dimensions of the DOMRectReadOnly objects passed to setShape() are specified in Device Independent Pixels (DIPs) within the local coordinate space of the operating system window. At 100% page zoom, 1 DIP corresponds to 1 CSS pixel.

When the user agent applies the shape to the underlying operating system window:

• Fractional Coordinates: While DOMRectReadOnly properties (x, y, width, height) accept floating-point numbers, the host operating system window shape primitives operate on integer pixel boundaries. When applying the shape, fractional DIP coordinate values are truncated to integers and clamped to the range of a 32-bit signed integer.
• Device Pixel Ratio (DPR): On high-density displays (where devicePixelRatio is not 1.0), the host window compositor automatically scales DIP coordinates by the display's device scale factor to determine physical device pixel boundaries. Developers do not need to perform manual coordinate scaling.
• Page Zoom: Because coordinates operate in window DIPs rather than document CSS pixels, page zoom does not scale the window shape. Developers only need to adjust coordinates on page zoom changes if they intend for the window shape to scale alongside zoomed DOM content.

The Window Shape API extends the IsolatedWebApp interface.

WebIDLpartial interface IsolatedWebApp {
  Promise<undefined> setShape(sequence<DOMRectReadOnly> rects);
};

The setShape(|rects|) method customizes the shape of the window. When called, the user agent does the following steps:

1. Let promise be a new promise.
2. Let window be the current global object.
3. If the display mode of window is not unframed, reject promise with an InvalidStateError and return promise.
4. If rects's size is greater than 10000, reject promise with a TypeError and return promise.
5. Let convertedRects be an empty list of rectangles.
6. Let hasMinimumSizeRect be false.
7. For each rect of rects:
   1. If any of rect's x, y, width, or height is not finite, reject promise with a TypeError and return promise.
   2. If rect's width is less than 0 or rect's height is less than 0, reject promise with a TypeError and return promise.
   3. If rect's width is greater than or equal to 10 and rect's height is greater than or equal to 10, set hasMinimumSizeRect to true.
   4. append a new rectangle with x, y, width, and height set to the corresponding values from rect truncated to an integer and clamped to the range of a 32-bit signed integer, to convertedRects.
8. If rects's size is greater than 0 and hasMinimumSizeRect is false, reject promise with a TypeError and return promise.
9. Run these steps in parallel:
   1. Let targetWindow be the OS window associated with the current global object.
   2. If targetWindow is null, reject promise with InvalidStateError and abort these steps.
   3. If the display mode of the current global object is not unframed, reject promise with InvalidStateError and abort these steps.
   4. Ask the host operating system to set targetWindow's shape to the union of convertedRects, which are in the host operating system window's Device Independent Pixel (DIP) coordinate space.
   5. resolve promise with undefined.
10. Return promise.