aaddrick--claude-desktop-debian/docs/upstream-reports/electron-wco-linux-bugs.md

Upstream report draft: three WCO-on-Linux Electron bugs (Bugs A/B/C)

Technical extraction of the three Linux WCO bugs surfaced by the 2026-04 topbar investigation, preserved here because the diagnosing doc (linux-topbar-shim.md) was archived when the v3.0.0 rebase deleted the wco-shim. Filing target is electron/electron GitHub Issues.

Before filing: the probes below were captured 2026-04-29 on Electron 41 / Chromium 146 via our then-shipped frameless builds. The official Linux build runs Electron 42.5.1 and ships frame:true-style windows, so each bug needs re-verification on a current Electron Fiddle (not a Claude build) before it goes upstream. Run the drafts through the voice workflow at filing time.

Bug A — WCO @media query doesn't match where WCO is otherwise active

In the main-window webContents of a frame:false + titleBarStyle:'hidden' + titleBarOverlay:{...} BrowserWindow on Linux X11, three of the four documented WCO detection points agree and the fourth is broken:

signal	value (2026-04-29)
navigator.windowControlsOverlay.visible	true
windowControlsOverlay.getTitlebarAreaRect()	1131×40 (matches config)
env(titlebar-area-width) via custom-property indirection	1131px
matchMedia('(display-mode: window-controls-overlay)').matches	false

Minimal repro after did-finish-load:

const wco = navigator.windowControlsOverlay;
const r = wco.getTitlebarAreaRect();
const s = document.createElement('style');
s.textContent = ':root { --w: env(titlebar-area-width) }';
document.head.appendChild(s);
({
  visible: wco.visible,                                              // true
  rect: { width: r.width, height: r.height },                        // populated
  cssEnvWidth: getComputedStyle(document.documentElement)
    .getPropertyValue('--w'),                                        // populated
  mediaQueryMatches:
    matchMedia('(display-mode: window-controls-overlay)').matches,   // false
});

Impact: any page that follows the documented @media detection pattern concludes WCO is inactive on Linux even when it is active. This is the most actionable of the three.

Bug B — WCO state doesn't propagate to BrowserView webContents

Same parent BrowserWindow, probing the attached BrowserView instead of the main webContents: visible is false, the rect is 0×0, env(titlebar-area-width) is empty, and the media query is false. A WCO-aware page hosted in a BrowserView never sees WCO regardless of parent configuration.

Caveat for the filing text: this may be working-as-designed webContents isolation (each webContents independent). Frame it as a question, not a defect claim, and note BrowserView's deprecation in favor of WebContentsView — re-verify against WebContentsView first; if it reproduces there, that is the version worth filing.

Bug C — implicit, non-overridable drag region on frame:false Linux windows

The top strip of a frameless window eats mouse events at the WM level on Linux, and no page- or app-level configuration can reclaim it. The 2026-04 investigation ruled out every configurable source:

• CSS -webkit-app-region: no-drag !important on the affected elements — computed style flips, clicks still dead
• MutationObserver stripping the draggable class — DOM clean, clicks dead
• setSize jiggle and hide/show cycles — no effect
• Omitting titleBarOverlay entirely — no effect
• Omitting titleBarStyle:'hidden' too — no effect
• frame: true — clicks work

So the trigger is frame:false itself: Chromium's ozone backend appears to install an implicit drag region for the top of frameless windows, and the region map is sticky — pushed to the WM at first paint and not refreshable from CSS or DOM mutations afterwards. Confirmed on both X11 and native Wayland (--ozone-platform=wayland) on 2026-04-29, so it is not an X11-only quirk. Characterizing the exact source needs ui/ozone/platform/{x11,wayland}/ inspection; programmatic .click() fires while real mouse clicks die, which is the diagnostic separating this from CSS/JS causes (recipe in the archived doc).

Combined impact of A + B + C: WCO is effectively unusable on Linux — detection is broken for media-query consumers, embedded views never see it, and the frameless mode it requires makes the top of the page unclickable.

Filing checklist

1. Re-verify each bug on current Electron via Fiddle (A and C are quick; B needs a WebContentsView variant).
2. Draft the issue text through the aaddrick-voice workflow, one issue per bug (A and C stand alone; B may fold into A's issue as a related observation if it turns out to be by-design).
3. File at https://github.com/electron/electron/issues, link back to the archived investigation doc for provenance.

---

Written by Claude Fable 5 via Claude Code