Enable edge-to-edge display cutout in fullscreen mode by TalviFox · Pull Request #7618 · home-assistant/android

TalviFox · 2026-10-13T03:02:46Z

Summary

This PR allows the WebView canvas to extend behind the camera hole punch in fullscreen mode, and removes the old status bar overlay guardrail in FrontendScreen.kt.

What changed:

Configured layoutInDisplayCutoutMode = SHORT_EDGES in LaunchActivity when fullscreen is toggled. Without this, Android defaults to letterboxing the window when system bars are hidden.
Removed statusBarColor.Overlay in FrontendScreen. This was originally added as a defensive measure for frontend#29125 and drawer contrast, but modern Lovelace already handles safe area padding cleanly via CSS env(safe-area-inset-top).
Passed the real top inset (pxToDp(...)) to onSafeAreaInsetsChanged instead of hardcoding 0f.

Impact:

Standard mode: Unchanged. Headers, system bars, and drawer contrast behave normally.
Fullscreen mode: Drops the artificial black bar on hole-punch displays. CSS safe areas dynamically protect cards and alert banners from colliding with the physical camera.
Verified on hardware (Pixel 9 Pro XL).

Checklist

New or updated tests have been added to cover the changes following the testing guidelines.
The code follows the project's code style and best_practices.
The changes have been thoroughly tested, and edge cases have been considered.
Changes are backward compatible whenever feasible. Any breaking changes are documented in the changelog for users and/or in the code for developers depending on the relevance.
I have read the Open Home Foundation AI Policy.

Select exactly one option that describes AI usage in this contribution:

I have not used AI for this contribution.
AI assistance was used for this contribution.
AI fully generated the code for this contribution, but I've reviewed and understood it before submitting and will respond without AI during review.

Screenshots

Standard Mode (App bar & system status bar render untouched)

Fullscreen Mode (True edge-to-edge behind the hole punch)

Safe Area Positioning (Standard HA UX and header remain properly positioned below safe area)

HA UX properly positioned below safe area

Any other notes

Empirical testing details and side-by-side hardware behavior across alert banners were documented in the follow-up comment on issue #7554.

- Configure layoutInDisplayCutoutMode = SHORT_EDGES in FullscreenEffect - Remove artificial status bar overlay in SafeHAWebView - Report real top safe area insets to frontend via pxToDp - Obsolete frontend#29125 guardrail: modern Lovelace properly handles env(safe-area-inset-top) in CSS, eliminating the need for a native top letterbox strip while preserving drawer contrast in standard mode. Fixes home-assistant#7554

home-assistant

Hi @TalviFox

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

home-assistant · 2026-10-13T03:02:53Z

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

Copilot

🟡 Changes recommended

Legacy frontends receive neither the removed native top guardrail nor CSS safe-area insets, leaving content beneath the status bar.

1 open finding

Removing top guardrail breaks older servers without safe-area handling · New

What changed in this PR

Fixes fullscreen display-cutout letterboxing while forwarding the actual top safe-area inset to compatible frontends.

Changes:

Configures cutout layout mode with fullscreen state.
Removes the fixed top overlay and reports the real top inset.

File	Description
`LaunchActivity.kt`	Updates display-cutout mode during fullscreen changes.
`FrontendScreen.kt`	Removes the top overlay and reports the top safe-area inset.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

-    val statusBarColor = contentState?.statusBarColor ?: fallbackColor
    val backgroundColor = contentState?.backgroundColor ?: fallbackColor

    Column(modifier = Modifier.fillMaxSize()) {


Stale

TimoPtr

I'm not confident merging this.

TimoPtr · 2026-10-13T06:55:32Z

    val backgroundColor = contentState?.backgroundColor ?: fallbackColor

    Column(modifier = Modifier.fillMaxSize()) {
-        // The top is never drawn edge-to-edge: we always reserve and color the status bar strip.


You cannot simply remove it like this. We need to keep it for old servers with issues at the top. Also we did enable it at some point but doing so breaks on some screen not only on the drawer. It could be on apps for instance like Music Assistant that takes over the UI. We cannot remove it until we have a way to ensure that the frontend is not drawing a color that would hide the content of the status bar and today it's not guaranteed.

TimoPtr · 2026-10-13T06:59:41Z

+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+                window.attributes = window.attributes.apply {
+                    layoutInDisplayCutoutMode = if (isFullScreen) {
+                        WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES


Could you share a screenshot of the difference between the two?

TimoPtr · 2026-10-13T07:12:37Z

@jpelgrom it seems that it is enabled on iOS now with the issue and no complains so far (we might be over protective here?), but I still have some concerned that it might break at any moment of time.

Also this PR needs to be adjusted for old server.

Restore statusBarColor.Overlay on the top window insets when serverHandleInsets is false. This ensures legacy Home Assistant servers that do not consume raw insets continue to have their top status bar protected, matching the behavior already in place for the left and right window insets. Modern servers (> 2026.2) continue reporting real insets via ReportSafeAreaInsetsEffect.

TalviFox · 2026-10-13T17:43:48Z

@TimoPtr Updated.

Restored statusBarColor.Overlay inside if (!serverHandleInsets) in FrontendScreen.kt. Legacy servers that do not process safe-area insets continue to have their top status bar protected like before, matching how the sides are handled. Modern servers (> 2026.2) receive real insets via ReportSafeAreaInsetsEffect.

Here is the cutout comparison tested on a Pixel 9 Pro XL:

Without SHORT_EDGES, Android defaults to letterboxing the viewport, leaving large dead bars around the display cutout and navigation areas in immersive mode.
With SHORT_EDGES, dashboards seamlessly extend edge-to-edge across the entire display while remaining functional.

Fullscreen Immersive View

Default (Letterbox)	Patched E2E (Menu Open)	Patched E2E (Fullscreen)

Card Dashboard View

Default (Letterbox)	Patched E2E (Menu Open)	Patched E2E (Header Hidden)

jpelgrom · 2026-10-14T20:47:21Z

we might be over protective here?

Yes, that very well could be true. Edge to edge with all Android versions + fullscreen is just hard to get 100% correct.

What is meant with "Patched E2E (Menu Open)"? I do not see a menu in the screenshots.
Can you test with an app which has Ingress support ("Open web UI" button) and takes over the UI, like Music Assistant as mentioned here? If not maybe @TimoPtr can test this one :)

TalviFox · 2026-10-14T21:05:17Z

@jpelgrom

By "Patched", I meant the debug APK with this PR's code applied. "Menu Open" just referred to the top dashboard header / tab navigation bar being visible versus completely hidden in fullscreen.
I'll see if I can get some Ingress testing done on my end as well, but @TimoPtr should probably verify with Music Assistant too just to have multiple eyes and devices on it. ;)

TalviFox · 2026-10-14T21:29:16Z

@jpelgrom Tested Music Assistant on the Pixel 9 Pro XL as well: safe areas and layout hold up cleanly in fullscreen. Top header controls and bottom player bar remain fully accessible with no cutout collisions.

TalviFox · 2026-10-14T21:49:03Z

Also tested rapid screen rotation in Music Assistant:

Rotating between landscape and portrait does show standard WebView viewport re-layout latency (padding shifts slightly until re-focused), but crucially, no interactive UI elements or buttons are ever permanently clipped or rendered behind the camera punch-hole. It degrades safe rather than destructive.

The empty area shows up left or right depending on the the previous rotation.

TimoPtr · 2026-10-15T12:14:05Z

-                .padding(insets.only(WindowInsetsSides.Horizontal).asPaddingValues()),
-        )
+        // The top status bar guardrail is retained for legacy servers (< 2026.2) where the frontend does not handle safe areas.
+        if (!serverHandleInsets) {


Unfortunately I think this is not enough from what I remember at the moment we've introduced this flag it was not working properly so we should enable this starting on the release you've tested, I know @bgoncal fixed a lot of issues in the frontend recently about safe area. I would gate this to 2026.10 to be safe @jpelgrom any opinion.

Testing this is always painful since we have so many screen on the frontend, I want this in the next beta so we can have feedbacks before a release in prod like we did last time (that led us to keep the top bar).

TalviFox added 3 commits October 13, 2026 01:53

trigger build

6802809

chore: remove local build workflow

573ef71

Copilot AI balanced review requested due to automatic review settings October 13, 2026 03:02

home-assistant Bot previously requested changes Oct 13, 2026

View reviewed changes

home-assistant Bot added the cla-needed label Oct 13, 2026

home-assistant Bot marked this pull request as draft October 13, 2026 03:02

Copilot started reviewing on behalf of TalviFox October 13, 2026 03:03

View session

TalviFox changed the title ~~Fix/hardcoded safe area~~ fix(frontend): enable edge-to-edge display cutout in fullscreen mode Oct 13, 2026

Copilot AI reviewed Oct 13, 2026

View reviewed changes

Comment thread app/src/main/kotlin/io/homeassistant/companion/android/frontend/FrontendScreen.kt

val statusBarColor = contentState?.statusBarColor ?: fallbackColor

val backgroundColor = contentState?.backgroundColor ?: fallbackColor

Column(modifier = Modifier.fillMaxSize()) {

home-assistant Bot added cla-recheck cla-signed and removed cla-recheck cla-needed labels Oct 13, 2026

TalviFox marked this pull request as ready for review October 13, 2026 03:23

TimoPtr reviewed Oct 13, 2026

View reviewed changes

TalviFox added 2 commits October 13, 2026 11:56

removed testing build_apk.yml for PR

bbdf56e

github-advanced-security Bot found potential problems Oct 13, 2026

View reviewed changes

TalviFox added 2 commits October 14, 2026 02:28

Use SdkVersion.isAtLeast for display cutout version check

ca05deb

Merge branch 'main' into fix/hardcoded-safe-area

808510a

jpelgrom changed the title ~~fix(frontend): enable edge-to-edge display cutout in fullscreen mode~~ Enable edge-to-edge display cutout in fullscreen mode Oct 14, 2026

TimoPtr added the wait next stable release Wait until the next stable release is widely available, because extended testing/review is needed label Oct 15, 2026

TimoPtr reviewed Oct 15, 2026

View reviewed changes

Conversation

TalviFox commented Oct 13, 2026

Summary

What changed:

Impact:

Checklist

Screenshots

Standard Mode (App bar & system status bar render untouched)

Fullscreen Mode (True edge-to-edge behind the hole punch)

Safe Area Positioning (Standard HA UX and header remain properly positioned below safe area)

Any other notes

Uh oh!

home-assistant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

home-assistant Bot commented Oct 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

TimoPtr left a comment

Choose a reason for hiding this comment

Uh oh!

TimoPtr Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

TimoPtr Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

TimoPtr commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TalviFox commented Oct 13, 2026

Fullscreen Immersive View

Card Dashboard View

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jpelgrom commented Oct 14, 2026

Uh oh!

TalviFox commented Oct 14, 2026

Uh oh!

TalviFox commented Oct 14, 2026

Uh oh!

TalviFox commented Oct 14, 2026

Uh oh!

TimoPtr Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

TimoPtr commented Oct 13, 2026 •

edited

Loading