Skip to content

fix(dashboard): zero the top safe-area inset in in-browser contexts - #9838

Merged
bolichen97 merged 1 commit into
mainfrom
fix/browser-mode-top-safe-area
Sep 10, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/browser-mode-top-safe-area

Conversation

@patrigao

@patrigao patrigao commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

On Android browsers whose WebView reports a display-cutout inset, the dashboard renders a dead ~34px band between the browser's URL bar and the app's top bar. The band is inert — it is the shell's p-safe top padding, not a control — so the mobile UX appears to have "a bar at the top that does nothing".

Root cause: env(safe-area-inset-top) is only meaningful when the viewport actually extends under the status bar / cutout. With browser chrome on screen, the UA's own bar already sits below the cutout — Safari reports 0 there, but Android WebView-based browsers report the cutout height regardless of where the web view sits. The shell (p-safe, from #5463) then double-insets: URL bar + spurious padding.

Why it matters

Every user reaching the dashboard through a WebView-based mobile browser (corporate wrappers, in-app browsers) loses ~34px of a phone screen to an inert band and gets a broken-looking header. The iPhone-notch PWA case #5463 fixed must keep working at the same time.

What changed (motivation → approach → change)

  • Symptom: dead band above the header on Android WebView browsers; none on iPhone PWA, none on desktop.
  • Root cause: bare env(safe-area-inset-top) trusted in contexts where the top inset cannot be real. The app only extends under the cutout when it IS the window — i.e. an installed PWA. display-mode is exactly that signal.
  • Change: the safe-area tailwind plugin routes the TOP edge through var(--safe-area-top, env(safe-area-inset-top)); index.css sets --safe-area-top: 0px by default and re-enables env(safe-area-inset-top, 0px) only under (display-mode: standalone), (display-mode: fullscreen). All top utilities (p-safe, top-safe, top-safe-offset-*, top-safe-or-*) inherit the gate from the plugin. Bottom/left/right stay bare env() — those insets are real even in-browser (iOS landscape notch flanks, home indicator with a minimized toolbar). The one raw top-inset consumer outside the utilities (design-critique lightbox close button) moves onto the same variable.

Per display mode:

Context env(top) Before After
iOS Safari tab (portrait) 0 no inset no inset (unchanged)
iOS installed PWA, notch ~59px inset inset (unchanged — standalone matches)
Android Chrome tab 0 no inset no inset (unchanged)
Android WebView browser over a cutout cutout height (spurious) dead band no inset (fixed)
Android installed PWA (WebAPK), cutout real inset inset (unchanged)

Tests

  • safeArea.guard.test.ts gains a source-pinning test for both halves of the gate (plugin routes top through the variable; index.css declares the 0px default and the display-mode re-enable). jsdom implements neither env() nor display-mode, so — like the compositor test that pins the drawer's left inset — the invariant is pinned at the source; reverting either half fails the test instead of silently reopening the band on physical hardware only.
  • Existing safe-area guard scans and mobilePanels.compositor.test.ts pass unchanged (33/33 across the two files).

Manual verification

  • Reproduced and verified fixed on a physical Android phone (WebView-based browser, cutout device): the ~34px dead band above the top bar is gone after this change; the top bar sits flush under the browser chrome.
  • npm run build verified: emitted CSS carries :root{--safe-area-top:0px}, the display-mode gate, and .p-safe{padding-top:var(--safe-area-top,env(safe-area-inset-top));…}.
  • npx tsc --noEmit and eslint on touched files: clean.

Screenshots / video

Rendered from the built dist at 390×700 (served statically without a backend, hence the offline noise in the status capsule — unrelated to this change). The "before" state is simulated by setting --safe-area-top: 34px, the value measured on the reporting device; it is byte-for-byte the padding the old bare-env() form produced there, and also what a real standalone PWA under a cutout still gets after this change.

Before (spurious inset) After (browser mode)
dead band above the top bar top bar flush under browser chrome

Related Issues

no linked issue: found while using the dashboard from an Android WebView browser; no existing issue covers it.

Pattern harvest

Rule candidate: review-prompt
Pattern: "env(safe-area-inset-top) trusted outside standalone/fullscreen display modes — with browser chrome on screen the top inset cannot be real; route top-inset reads through the display-mode-gated variable."

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A: behavior documented in the plugin/CSS comments and the pinned test
  • No secrets, credentials, or internal references in the diff

@patrigao
patrigao requested review from a team and pepmach September 10, 2026 02:44
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 10, 2026
@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 80780e3f84868c45960777aa89020eed69a4df85 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 80780e3

Verdict parsed from the review's SHA-scoped output markers for commit 80780e3f84868c45960777aa89020eed69a4df85.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 80780e3f84868c45960777aa89020eed69a4df85: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 80780e3f84868c45960777aa89020eed69a4df85 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Right layer (the plugin, so every top utility inherits the gate), top-edge-only scope, device-verified, and the fix is a clean CSS revert if wrong.

Watch

display-mode is a proxy for "browser chrome on screen", and the two diverge in a chromeless edge-to-edge WebView wrapper (increasingly common with Android 15's enforced edge-to-edge): there display-mode is browser but the cutout inset is real, so this gate zeroes it and the header slides under the status bar — the inverse of the band being fixed. No better web-exposed signal exists, so this is a deliberate tradeoff, not a flaw; a human should just know which failure mode was chosen.
Clears when: the residual is verified or recorded — e.g. a check on one chromeless edge-to-edge WebView, or a comment in the plugin naming this known inverse case so a future report is triaged as the tradeoff, not a new bug.

[DESIGN-REVIEWED] 80780e3

@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 80780e3f84868c45960777aa89020eed69a4df85 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 80780e3

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 80780e3f84868c45960777aa89020eed69a4df85: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 80780e3f84868c45960777aa89020eed69a4df85 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

No existing display-mode mechanism duplicated; the variable's consumers count 2; no bare top-inset readers remain outside the gate. The review is complete — final output follows.

First-Principles-Verdict: PASS

Manual verification covers only the broken WebView case — confirm an installed PWA (iOS notch, Android WebAPK) still gets its inset before merge.

What this change ships

Inventory (6 items) — 5 justified

Intent: remove the inert ~34px band above the header when the dashboard runs in a WebView-based mobile browser over a display cutout, while keeping the installed-PWA notch inset — a FIX.

  1. Top safe-area padding disappears in ordinary browser tabs/WebView browsers; kept only when installed as a PWA — justified
  2. New global CSS variable --safe-area-top (2 counted consumers: tailwind plugin, design-critique lightbox) — justified
  3. Design-critique lightbox close button's top offset now follows the same gate — justified
  4. New source-pinning test locks both halves of the gate — justified
  5. Guard-test fix-it message now recommends the gated variable for top edges — justified
  6. Two before/after screenshots committed under temp-screenshots/ — rides along (repo convention: 1,585 existing files there, named in .gitignore as deliverables)

Provenance: reproduction written in the description with a measured value and device, plus a test that fails on base. Cause-level: the gate sits at the single plugin chokepoint; grep for safe-area-inset-top outside tests finds 0 remaining ungated top readers.

[FIRST-PRINCIPLES-REVIEWED] 80780e3

@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 80780e3f84868c45960777aa89020eed69a4df85 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

The diff is a layout-only fix — no controls added or changed; both states are screenshotted, the blind read ran, and the reader confirmed the "before" band read as wasted space or a mistake, which is exactly what the PR removes. The one alarming thing in the screenshots (the red overlapping status capsule) is pre-existing offline noise, untouched by this diff.

UX-Verdict: PASS

The fix deletes a dead band the blind reader itself called "wasted space or something that failed to appear" — comprehension confirmed, nothing new to learn.

Watch

  • Pre-existing, not this diff: at 390px the status capsule's red warning glyphs overlap the "Local" tab strip (visible in both screenshots; blind reader: "I could not even tell which of the overlapping things my finger would hit… would not dare tap it"). Same mobile-header surface this PR repairs — worth filing as its own issue so it isn't mistaken for offline-only noise.

[UX-REVIEWED] 80780e3

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 10, 2026
With browser chrome on screen the UA's own bar already sits below the
status bar / display cutout, so a non-zero env(safe-area-inset-top) there
is spurious -- Android WebView browsers report the cutout height regardless
of where the web view actually sits, which painted a dead ~34px band above
the app header (p-safe on the shell). Only when the app IS the window
(installed PWA: standalone/fullscreen display mode) does the viewport
really extend under the cutout.

Route the TOP edge of the safe-area tailwind utilities through
--safe-area-top, which index.css zeroes by default and re-enables from
env() only under (display-mode: standalone) or (display-mode: fullscreen).
Bottom/left/right stay bare env() -- those insets are real even in-browser
(iOS landscape notch flanks, home indicator). The one raw top-inset
consumer (design-critique lightbox close) moves onto the same variable,
and safeArea.guard.test.ts pins both halves of the gate at the source.
@patrigao
patrigao force-pushed the fix/browser-mode-top-safe-area branch from 715ca98 to 80780e3 Compare September 10, 2026 03:27
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 10, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 10, 2026 04:41

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maintainer review (agent-assisted, on behalf of @bolichen97), head 80780e3f8.

Verified the top-inset gate end to end: tailwind.config.js:40-42 routes only the top edge through var(--safe-area-top, env(safe-area-inset-top)), index.css:298 declares --safe-area-top: 0px, and index.css:328-330 re-enables the env inset under display-mode: standalone/fullscreen, so the iOS PWA case keeps its notch inset while in-browser contexts drop the duplicate. Screenshots pinned to head; 6 files accounted for.

Non-blocking notes:

  • display-mode: browser also matches a chromeless Android WebView drawn edge-to-edge, which now loses a real top inset — niche, opposite of the reported case, worth a sentence in the body.
  • website/docs/narrow-viewport.md:100 (the authoritative safe-area note) still describes the inset as bare env(); add a line about the display-mode gate so nobody reintroduces it.
  • safeArea.guard.test.ts:331 pins an exact single-quoted string; a regex tolerant of quote style would match the neighbouring assertions.

@bolichen97
bolichen97 merged commit c01c1a4 into main Sep 10, 2026
67 of 73 checks passed
@bolichen97
bolichen97 deleted the fix/browser-mode-top-safe-area branch September 10, 2026 05:01
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 10, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…irodotdev#9838)

With browser chrome on screen the UA's own bar already sits below the
status bar / display cutout, so a non-zero env(safe-area-inset-top) there
is spurious -- Android WebView browsers report the cutout height regardless
of where the web view actually sits, which painted a dead ~34px band above
the app header (p-safe on the shell). Only when the app IS the window
(installed PWA: standalone/fullscreen display mode) does the viewport
really extend under the cutout.

Route the TOP edge of the safe-area tailwind utilities through
--safe-area-top, which index.css zeroes by default and re-enables from
env() only under (display-mode: standalone) or (display-mode: fullscreen).
Bottom/left/right stay bare env() -- those insets are real even in-browser
(iOS landscape notch flanks, home indicator). The one raw top-inset
consumer (design-critique lightbox close) moves onto the same variable,
and safeArea.guard.test.ts pins both halves of the gate at the source.

Co-authored-by: Patrick Gao <patrigao@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants