Intent to Ship: Window shape API

[Chromestatus]

Contact emails

edm...@google.com, swetha...@google.com

Explainer

https://github.com/explainers-by-googlers/chromeos-iwa-apis/blob/main/window-shape-explainer.md

Specification

https://explainers-by-googlers.github.io/chromeos-iwa-apis

Design docs

https://docs.google.com/document/d/1zPr1QgS-bXsJE7nrO44zx9RBopR4gHuvHxfcqxsX5Ag/edit?tab=t.0#heading=h.pcgro84kqnh3

Summary

Window Shape API enables allowlisted [Isolated Web Apps](https://chromeos.dev/en/web/isolated-web-apps) on ChromeOS to customize their window shape. By enabling non-rectangular and non-contiguous window layouts, developers can implement unique user experiences (such as widgets, floating panels, and overlays) that match the look-and-feel of native applications. The API `window.chromeos.isolatedWebApp.setShape` requires the window to be in the unframed display mode and requires the window-management permission to be granted. Administrators can manage this feature with existing policies for window management: - [DefaultWindowManagementSetting](https://chromeenterprise.google/policies/#DefaultWindowManagementSetting) configures the default state for the window management for all apps. The policies below can override this default. - [WindowManagementAllowedForUrls](https://chromeenterprise.google/policies/#WindowManagementAllowedForUrls) allows IWAs with specified origins to enter unframed mode and set custom window shapes without any user interaction. - [WindowManagementBlockedForUrls](https://chromeenterprise.google/policies/#WindowManagementBlockedForUrls) blocks the permission for specified origins, forcing Chrome to remove any custom window shapes and fallback to other available display modes.

Blink component

UI>Browser>WebAppInstalls>Isolated

Web Feature ID

Missing feature

Motivation

No information provided

Initial public proposal

No information provided

TAG review

N/A - TAG review is not needed for IWA APIs https://crsrc.org/c/docs/website/site/blink/launching-features/isolated-web-apps/index.md;l=73;drc=a5459539e0dfc093d8dc137fb9f8a72ddf5dcbb3

TAG review status

Not applicable

Goals for experimentation

None

Risks

Interoperability and Compatibility

N/A, this feature is not meant to be implemented by other browsers.

Gecko: No signal

WebKit: No signal

Web developers: No signals

Other signals:

Ergonomics

N/A

Activation

N/A, the feature is a single JS API that follows the same behavior as a pre-existing Chrome App API. Developers already know how to use it.

Security

See https://github.com/explainers-by-googlers/chromeos-iwa-apis/blob/main/window-shape-explainer.md#security--privacy-considerations In summary: The custom shape can be used to create a hidden window, or for clickjacking. We mitigate this by requiring a minimum shape size of 10x10 pixels, and by enforcing an allowlist of partners that can use this API.

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

N/A

Debuggability

N/A

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

No
This feature is implemented as a Blink extensions for Chrome on ChromeOS. It will not be available in any other platform.

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

No

Flag name on about://flags

enable-chromeos-isolated-web-app-set-shape

Finch feature name

No information provided

Non-finch justification

No information provided

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

False

Availability expectation

Feature is available only in Chrome on ChromeOS, and only for allowlisted IWAs.

Adoption expectation

Feature is used by allowlisted IWAs within 12 months of launch in Chrome.

Adoption plan

Work with partners: The feature is currently available behind a feature flag in ChromeOS, and two partners already use it to develop new IWAs. The target release of their IWAs is 26Q4.

Non-OSS dependencies

Does the feature depend on any code or APIs outside the Chromium open source repository and its open-source dependencies to function?

N/A

Estimated milestones

Shipping on desktop

152

Anticipated spec changes

Open questions about a feature may be a source of future web compat or interop issues. Please list open issues (e.g. links to known github issues in the project for the feature specification) whose resolution may introduce web compat/interop risk (e.g., changing to naming or structure of the API in a non-backward-compatible way).

N/A

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5075144470036480?gate=6125215051546624

This intent message was generated by Chrome Platform Status.

[Alex Russell]

Hey folks,

I'm very excited to see this capability coming to the web!

At the same time, the shape of this proposal is not going to pass muster in current form.

First, we can't be embedding the name `chromeos` into APIs that can be used across platforms. We should hope and expect for a day when IWAs are lit up more broadly, so putting this in a CrOS-specific namespace is a bad smell. It also isn't clear that this should be prefixed with an IWA-specific namespace.

Second, it isn't clear that this making format is common to other masking formats on the web. I don't see a list of considered design alternatives for these (and other) API shape concerns in the Explainer, which in and of itself is concerning. Can you please reach out to a current or former TAG memeber in your org to get guidance on API shape?

Best,

Alex

[Edman Anjos]

Hi Alex, thanks a lot for your reply,
there's some additional context I can share about this feature:

* This feature is designed as a ChromeOS-specific Blink extension exclusively for Isolated Web Apps (IWAs). It is not a general web standard or cross-platform web API, and will not become one. Access is further restricted to allowlisted applications. Because the target audience and platform scope are so narrow, standardization is not a goal in this feature.

* We first proposed this style of APIs on blink-api-owners-discuss. `setShape` is our first (and currently only planned) API following this proposal. The use of `chromeos.isolatedWebApp.*` comes from the need of a namespace that won't pollute standard web or IWA API surfaces, or potentially other ChromeOS-only APIs.

* The API signature and behavior comes from the existing `chrome.app.window.setShape` API for Chrome Apps on ChromeOS. Partners are already familiar with the Chrome App API, so mirroring it for the IWA API greatly simplifies adoption.

I hope this clarifies things.

Thanks again,
Edman

[Chris Harrelson]

LGTM1

This is a very specific API just on ChromeOS, and the global variables are only visible to IWAs explicitly opted into it via controls on that OS. It doesn't set a new precedent.

This also aligns with the plan of action discussed on blink-api-owners-dsicuss.

--
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 visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/a2a7f5c3-e2f2-4c6e-97b3-79ecf2c040b0n%40chromium.org.

[Reilly Grant]

IWA OWNER LGTM

I would like to eventually see a version of this capability available cross-platform. However as discussed with Blink API OWNERS this ChromeOS-specific API is being proposed in a way that avoids accidentally burning it into the platform and will need to be redesigned if platform support is expanded.

Reilly Grant | Software Engineer | rei...@chromium.org | Google Chrome

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAOMQ%2Bw9vF8eew04g%3DBuwiGD2TCPhWCPLn3fT2PRRx_uHpxmGkA%40mail.gmail.com.

[Alex Russell]

 Hey Edman,

I think we should perhaps schedule a call. For context, IWAs were an initiative that I started with Mike West and Penny McLachlan, so I'm fully aware of the design constraints that can (and do) apply to them. The explicit design goal of IWAs is to avoid OS-specific designs and specs that cannot be plausibly interoperable. I don't understand this design as something that can't be made interoperable, and if there's a reason why, it would be good to see that called outsomewhere. Regardless, I'm not sure that reads on the namespace or API shape, and both remain problematic.

Marking this as "needs work" in chromestatus until we can confer.

Best,

Alex

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

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/a2a7f5c3-e2f2-4c6e-97b3-79ecf2c040b0n%40chromium.org.

--
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.

[Mike Taylor]

LGTM2 - we already discussed the chromeos namespace/Blink extension path over in https://groups.google.com/a/chromium.org/g/blink-api-owners-discuss/c/q_bRRc_RxBo?e=48417069. I do think Alex has good feedback on how to improve the explainer (which may be useful for future efforts that try to bring this to the interoperable web).

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/1f66a914-57ce-46d1-96b6-fcb8bd910b18n%40chromium.org.

[edmanp via Chromestatus]

Hi Alex, Mike, I have updated the explainer with new "Scope considerations" and "Alternatives considered" sections. PTAL https://github.com/explainers-by-googlers/chromeos-iwa-apis/blob/main/window-shape-explainer.md

[Rick Byers]

We discussed this in API owners today and Alex made a compelling argument for why there is no need to namespace-scope IWA APIs (they're already heavily scoped by the fact they exist only in the niche IWA operating environment). Alex, Reilly, Edman and I then met to discuss the tradeoffs further and agreed that we'd remove the namespace scoping (eg. window.setShape). 

Given this significant change, I suggest we reset the lgtm counter. I'm LGTM1 with this new plan (once the spec is updated to reflect it).

Thanks,

   Rick

On Mon, Jul 20, 2026 at 5:17 PM edmanp via Chromestatus <admin+...@cr-status.appspotmail.com> wrote:

Hi Alex, Mike, I have updated the explainer with new "Scope considerations" and "Alternatives considered" sections. PTAL https://github.com/explainers-by-googlers/chromeos-iwa-apis/blob/main/window-shape-explainer.md

--

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 visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/6a5e905a.77f2aaf9.76381.025e.GAE%40google.com.

[Mike Taylor]

LGTM2

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAFUtAY9RP7qS3WrHppLaDRxXKSTwznyi9xdaTwVeNOH8tXa0Pg%40mail.gmail.com.

[Chris Harrelson]

LGTM3

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/f1200b78-de2d-4b12-b64c-54e13a79150f%40chromium.org.

[Alex Russell]

Superfluous LGTM4; thanks for the flexibility, Edman.

Best,

Alex

On Thursday, July 30, 2026 at 4:51:24 PM UTC-7 Chris Harrelson wrote:

LGTM3

On Thu, Jul 30, 2026, 11:31 AM Mike Taylor <mike...@chromium.org> wrote:

LGTM2

On 7/29/26 4:27 p.m., Rick Byers wrote:

We discussed this in API owners today and Alex made a compelling argument for why there is no need to namespace-scope IWA APIs (they're already heavily scoped by the fact they exist only in the niche IWA operating environment). Alex, Reilly, Edman and I then met to discuss the tradeoffs further and agreed that we'd remove the namespace scoping (eg. window.setShape). 

Given this significant change, I suggest we reset the lgtm counter. I'm LGTM1 with this new plan (once the spec is updated to reflect it).

Thanks,

   Rick

On Mon, Jul 20, 2026 at 5:17 PM edmanp via Chromestatus <admin+edmanp@cr-status.appspotmail.com> wrote:

Hi Alex, Mike, I have updated the explainer with new "Scope considerations" and "Alternatives considered" sections. PTAL https://github.com/explainers-by-googlers/chromeos-iwa-apis/blob/main/window-shape-explainer.md

--
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.

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/6a5e905a.77f2aaf9.76381.025e.GAE%40google.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.

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAFUtAY9RP7qS3WrHppLaDRxXKSTwznyi9xdaTwVeNOH8tXa0Pg%40mail.gmail.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.