#53598: feat: add ELECTRON_DEBUG_DRAGGABLE_REGIONS debugging aid
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
Semver Impact
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