Allow for emulation of safe area insets

[sadym-chromium]

Partly addressing #772

Modern mobile devices frequently feature physical screen obstructions such as "the notch," camera cutouts (hole-punch displays), and software-defined system overlays (e.g., home indicators and status bars). To ensure web content remains usable on these devices, web developers rely on CSS environment variables—specifically env(safe-area-inset-*) to dynamically adjust their layouts.

Currently, WebDriver BiDi does not provide a mechanism to control these values, making it impossible for automated tests to verify "mobile-ready" layouts in an emulated environment.

Scenarios

• Mobile Device Emulation: Users must be able to simulate specific hardware profiles (e.g., an iPhone 15 or a Samsung Galaxy S24) where the safe area insets are pre-configured to match the physical properties of those devices.
• Content Visibility Testing: Users must be able to verify that critical UI elements (like fixed-position headers or "floating action buttons") are not obscured by a hardware cutout or system navigation bar.
• Dynamic Layout Reflow: Users must be able to test how a responsive site handles the repositioning of safe zones ensuring that content "safe zones" are respected without requiring a page reload (e.g., simulating the transition of a notch from the top to the side, or device orientation changes).
• Edge-to-Edge Experience: Enabling tests to verify that viewport-fit: cover behavior correctly expands content into the non-safe areas while maintaining readable margins via the environment variables.

Proposed Solution

We propose adding a new command browsingContext.setSafeAreaInsets

browsingContext.setSafeAreaInsets = {
  top: uint,
  right: uint,
  bottom: uint,
  left: uint,
}

[css-meeting-bot]

The Browser Testing and Tools Working Group just discussed Safe area insets.

The full IRC log of that discussion

<AutomatedTester> Topic: Safe area insets
<AutomatedTester> github: https://github.com//issues/1054
<tidoust> sadym: Insets, I'm not sure how well they are supported by all the browsers. It can be the camera area on the phone.
<tidoust> ... It's something that can be emulated, the question is: do we want to have it specified?
<AutomatedTester> q?
<AutomatedTester> q+
<AutomatedTester> ack next
<tidoust> AutomatedTester: I think we probably would want to have something like this. I'm not sure how common people would have it but I can see the watch example being quite useful for people to test on a smaller area.
<AutomatedTester> q?
<sasha> q+
<AutomatedTester> ack next
<tidoust> sasha: Firefox also supports it, so we could add it as well. I'm not sure whether it's a priority at the moment. Maybe in the future.
<tidoust> AutomatedTester: Consensus is we'll look into it at some point.