Intent to Ship: Controlled Frame API (available only to IWAs)

[Robbie McElrath]

Contact emails

rmce...@chromium.org, ze...@chromium.org

Explainer

https://github.com/WICG/controlled-frame/blob/main/README.md

Specification

https://wicg.github.io/controlled-frame

Summary

Adds a Controlled Frame API available only to Isolated Web Apps (IWAs).

This work will add a new Controlled Frame API which is only available to Isolated Web Apps (IWAs). Like WebView APIs on other platforms, Controlled Frame allows embedding all content, even third party content that can't be embedded in <iframe>. Controlled Frame also allows controlling embedded content with a collection of API methods and events.

For more info on Isolated Web Apps, see the IWA explainer: https://github.com/WICG/isolated-web-apps/blob/main/README.md

Blink component

Blink>ControlledFrame

TAG review

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

TAG review status

Pending

Risks

Interoperability and Compatibility

This is a new API available only within IWAs. As a new API, it is subject to the risk that other browsers may not implement it. However, other browsers must also implement IWAs, and for now we are advancing this to assist our dev partners that are migrating from Chrome Apps.

The API allows embedding third-party (non-IWA) content. The content will be loaded within dedicated storage partitions managed by the embedding application and won't have access to the same site's content as if it was loaded in a tab.

Gecko: No signal

WebKit: No signal

Web developers: The WebView API that Controlled Frame is based on has been used by developers for 15+ years for the use cases outlined in the explainer. Feedback for Controlled Frame specifically has been requested.

Other signals: Controlled Frame is very similar to WebView APIs. Work in W3C around WebViews is on-going, documenting their existing and potential uses. We have been participating in discussions and hope to offer insights with our design, implementation, and community feedback. Internal partners have requested embedding APIs that can be used in web apps.

Ergonomics

The Controlled Frame API is based on the Chrome Apps WebView API, which has had the benefit of years of developer partner experience and feedback. We included some adjustments to the API to ensure it fits into web technologies like permissions and permissions policy, incorporated developer partner feedback, and changed or removed some API elements based on need.

Activation

Developers must build an IWA to use the Controlled Frame API. The IWA they build must then be deployed, currently using managed distribution via enterprise policy. These hurdles present significant activation risk since each of these are new technologies and require interaction with multiple systems.

Once the IWA is built, using the Controlled Frame element may require some direct engagement since the methods used to interact with embedded content are complicated. We recommend additional developer documentation and outreach directly with development partners.

Security

Controlled Frame is only available to IWAs, which restricts the API so that it's not accessible to normal web pages and normal web applications.

Controlled Frame integrates with Permissions Policy and requires the IWA to include the "controlled-frame" policy-controlled feature in the IWA manifest in order for the feature to be enabled.

Controlled Frame containers inherit a permissions policy from the embedding frame and policy-controlled features are only available if those features are enabled in the embedding frame. Features that use permissions require the embedder to allow those permissions, and the embedder itself must already have that permission in order to allow the embedded content to use it.

WebView application risks

This API is not available on Android, and has no impact on Android WebView.

Debuggability

Console messages within a nested browsing context fire an event that the embedder can choose to display (e.g. to the user, via console.log() to show it in DevTools, etc).

Events are generated in the API for certain kinds of actions that occur within an embedded frame's lifetime.

DevTools is available within the embedded content.

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

No. The Controlled Frame API is not currently supported on Android. (This work is conceptually similar to Android WebView but is unrelated as this proposal targets building a WebView-related API for IWAs.)  Initially the API environment is exposed only on ChromeOS 

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

No. WPT does not support PWA/IWA test environments. Once that support is available, we can investigate adding IWA-focused WPT tests.

Until then, we have built a pseudo-WPT test environment so we can write WPT-like tests that work in an IWA context. These are available for review in the Chromium code repository:

//chrome/test/data/controlled_frame:

https://source.chromium.org/chromium/chromium/src/+/main:chrome/test/data/controlled_frame/

//chrome/browser/controlled_frame/controlled_frame_wpt_browsertest.cc:

https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/controlled_frame/controlled_frame_wpt_browsertest.cc?q=add_content_scripts&ss=chromium%2Fchromium%2Fsrc

DevTrial instructions

https://github.com/WICG/controlled-frame/tree/main/test_app

Flag name on about://flags

ControlledFrame

Finch feature name

None

Non-finch justification

None

Requires code in //chrome?

True

Tracking bug

https://crbug.com/40191772

Launch bug

https://launch.corp.google.com/launch/4283394

Measurement

https://chromestatus.com/metrics/feature/timeline/popularity/5205

Sample links

https://github.com/WICG/controlled-frame/tree/main/test_app

Estimated milestones

Shipping on desktop	136
DevTrial on desktop	114

Anticipated spec changes

We’re currently working on expanding many sections of the spec.

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5199572022853632?gate=5134483605422080

Links to previous Intent discussions

Intent to Prototype: https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAKcCwFPo79ELzrS5qDcbXNM9K71c1a964uqWpMxK0AZNzOXa1w%40mail.gmail.com

This intent message was generated by Chrome Platform Status.

[Domenic Denicola]

On Tuesday, March 18, 2025 at 8:39:21 AM UTC+9 Robbie McElrath wrote:

Contact emails

rmce...@chromium.org, ze...@chromium.org

Explainer

https://github.com/WICG/controlled-frame/blob/main/README.md

Specification

https://wicg.github.io/controlled-frame

This is a large specification effort, so thank you for working on it!

Unfortunately, it seems pretty incomplete right now. E.g. stuff like https://wicg.github.io/controlled-frame/#dom-htmlcontrolledframeelement-executescript step 7 or https://wicg.github.io/controlled-frame/#dom-htmlcontrolledframeelement-insertcss steps 6-8 are not really specification text, just explainer text in numeric list format. Similarly https://wicg.github.io/controlled-frame/#traverse-an-embedded-navigables-history has a pretty bad TODO. And stuff like https://wicg.github.io/controlled-frame/#validate-embedded-content also makes it seem like the specification is not ready.

To me it doesn't seem like this specification is at the level we require, i.e. enough to allow interoperable implementation between multiple engines.

Could you keep working on writing a complete specification, and come back to us for shipping approval when such a spec is ready?

I'm also concerned about the section at https://wicg.github.io/controlled-frame/#api-web-request , which basically seems to be saying that the proposal authors aren't working to create a web platform standard here, but instead ship a Chrome Apps API to the web. I don't know if that's an appropriate thing for us to approve through the Blink process. Even beyond the issue of creating a rigorous specification, that decision might need more discussion.

[Alex Russell]

Any updates here?

[Robbie McElrath]

We're now targeting M138 to give us more time to improve the spec.

There hasn't been any spec progress in the last 2 weeks due to some unfortunately timed vacations, but I'll be picking that up again starting today and responding to feedback from Reilly and Dominic.