MarshallOfSound

#53598: feat: add ELECTRON_DEBUG_DRAGGABLE_REGIONS debugging aid

Merged
Created: Sep 5, 2026, 4:53:26 PM
Merged: Sep 6, 2026, 12:55:35 PM
9 comments
Target: main

Summary

Adds the ELECTRON_DEBUG_DRAGGABLE_REGIONS environment variable. In unpackaged apps it paints the draggable region each WebContents hit tests against as translucent rectangles floating above the web contents, and logs every region update the renderer sends, the cost of computing the hit-test region, and periodic hit-test summaries.

Chromium changed how app-region cascades starting in Electron 44, and apps with custom title bars have had a hard time telling whether a region problem is in their CSS or in what Electron actually hit tests against. The overlay shows the region the main process uses rather than the CSS, so those differences are visible directly.

Nothing changes when the variable is unset: one cached environment lookup per process and a null check per hit test.

Test plan

Ran a frameless test app with ELECTRON_DEBUG_DRAGGABLE_REGIONS=1 ELECTRON_ENABLE_LOGGING=1 on macOS and verified the overlay follows the window through moves, resizes, and DevTools docking, drag and no-drag areas match the page, and log lines appear for updates, bounds changes, and hit tests. Also confirmed with a Perfetto trace that region messages from the renderer are delayed during macOS live resize, which the overlay stamp and the staleness log line now make visible.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GeVPx9L9YnfSk7an5fALZi

Notes: Added the ELECTRON_DEBUG_DRAGGABLE_REGIONS environment variable, which visualizes and logs draggable regions in unpackaged apps to help debug custom title bars.

Backports

43-x-y
In-flight
PR Number
#53633
Waiting to be merged
44-x-y
In-flight
PR Number
#53627
Waiting to be merged
45-x-y
In-flight
PR Number
#53626
Waiting to be merged

Semver Impact

Major
Breaking changes
Minor
New features
Patch
Bug fixes
None
Docs, tests, etc.

Semantic Versioning helps users understand the impact of updates:

  • Major (X.y.z): Breaking changes that may require code modifications
  • Minor (x.Y.z): New features that maintain backward compatibility
  • Patch (x.y.Z): Bug fixes that don't change the API
  • None: Changes that don't affect using facing parts of Electron