PSA: Surface Embed is here

28 views

Skip to first unread message

Keren Zhu

unread,

Sep 24, 2026, 2:39:52 PM (4 days ago) Sep 24

to Chromium-dev, Chromium Embedders

Hi Chromium Developers,

If you don’t use GuestView or GuestContents, you can stop reading here.

We are announcing the General Availability of Surface Embed, a new, secure mechanism for embedding content::WebContents inside trusted WebUI documents.

If you currently use GuestContents, please migrate to Surface Embed. If you currently use GuestView, we encourage you to try out Surface Embed as well.

Getting Started & Documentation

Documentation:
- USER_GUIDE.md and README.md
- guest_view_vs_surface_embed.md
Reference Implementations:
- WebUI Browser (//chrome/browser/ui/webui_browser/)
- WebUI Examples (//ui/webui/examples/)
Design Docs:
- Background, Goals and Planning
- Plugin-based Design and Approval

Migration from `GuestContents`

With Surface Embed now enabled by default, GuestContents is deprecated. We encourage all downstream embedders currently using GuestContents to begin migrating to Surface Embed. We will maintain GuestContents while existing embedder migrations are in progress. We expect to remove GuestContents in early 2027.

Migration from `GuestView`

Surface Embed is NOT a drop-in replacement for GuestView. However, we strongly encourage you to evaluate Surface Embed for its significantly reduced complexity, closed-by-default attack surface, and better maintenance state. Please read guest_view_vs_surface_embed.md.

Feedback & Bug Reporting

If you encounter any issues or have feature requests:

File / Track Bugs: Chromium > UI > Browser > WebUI Browser > Surface Embed.
Questions: Reach out on #chrome-embedded-webcontents on Chromium Slack.
Code Reviews: Send CLs to surface-em...@google.com.

Acknowledgments

Surface Embed is the result of a multi-quarter collaboration across the Chromium project.

A huge thank you to everyone who made this possible:

Engineering: Cammie Smith Barnes (cam...@chromium.org), Dave Risney (david....@microsoft.com), Keren Zhu (kere...@chromium.org), Liang Zhao (liang...@microsoft.com), Maksim Orlovich (morl...@chromium.org), Paul Jensen (paulj...@chromium.org), Robert Liao (rob...@chromium.org), Sam Fortiner (sam...@microsoft.com), Tom Lukaszewicz (tl...@chromium.org).
Chrome Security Approval & //content Reviewers: Alex Moshchuk (ale...@chromium.org), Charlie Reis (cr...@chromium.org), Nasko Oskov (na...@chromium.org); Dave Tapuska (dtap...@chromium.org), Kevin McNee (mc...@chromium.org).

We would also like to thank Fabio Rocha, Kevin Babbitt, Kevin DiClemente, Khushal Sagar, and Mike Jackson for their early input and technical discussions.