Support WebView2 Window Controls Overlay (IsWindowControlsOverlayEnabled) on Windows

[tuyangJs]

Feature Request: Implement Window Controls Overlay API

Is your feature request related to a problem? Please describe.

When building modern desktop applications with Wry, developers often want to create custom title bars that seamlessly integrate with their web content. Currently, achieving this requires complex workarounds:

1. Manual implementation burden: Developers need to manually implement window control buttons (minimize, maximize, close) and dragging functionality using CSS properties like -webkit-app-region: drag or --app-region: drag
2. Inconsistent appearance: Custom-implemented window controls often don't match the system's native appearance, especially when system themes change
3. Complex behavior handling: Implementing proper window state management (maximize/minimize/restore) requires additional native code integration
4. Cross-platform compatibility: Solutions that work on one platform may not work on another
5. Accessibility challenges: Custom controls often lack proper accessibility support

This results in increased development time, inconsistent user experiences, and higher maintenance costs for developers building modern desktop apps with Wry.

Describe the solution you'd like

I would like Wry to implement the Window Controls Overlay API, similar to what WebView2 already provides. This API would allow developers to:

1. Display native window controls on top of web content: Let Wry draw the system's native window control buttons (minimize, maximize, close) on top of the web view
2. Customize title bar appearance: Allow developers to create custom title bars in their web content while preserving native window controls
3. Maintain native functionality: Ensure the window control buttons still properly maximize, minimize, and close the window
4. Access CSS environment variables: Provide access to CSS env() variables like titlebar-area-x, titlebar-area-y, titlebar-area-width, titlebar-area-height to help position content around the controls
5. JavaScript API for control: Offer a JavaScript API to detect when the window controls overlay is visible, its geometry, and to handle events
6. Cross-platform support: Implement this feature consistently across all platforms Wry supports

Key features requested:

• ✅ Native window control buttons rendered on top of web content
• ✅ Customizable title bar area in web content
• ✅ CSS environment variables for positioning
• ✅ JavaScript API for overlay management
• ✅ Consistent behavior across platforms
• ✅ Proper accessibility support
• ✅ Theme-aware controls that match system appearance

Describe alternatives you've considered

1. Fully custom title bars: Implementing window controls entirely in web content using CSS and JavaScript. This approach is flexible but requires significant effort to match native appearance and behavior.

2. System default title bars: Using the platform's default title bar. This provides native appearance and behavior but offers limited customization options.

3. Electron's title bar API: Electron provides a similar feature, but it's tied to Electron's ecosystem and not available in Wry.

4. Platform-specific native code: Writing platform-specific native code to implement custom title bars. This approach is complex and difficult to maintain across multiple platforms.

5. CSS app-region properties: Using -webkit-app-region: drag or --app-region: drag to create draggable areas. This works for dragging but doesn't solve the problem of native window controls.

Additional context

WebView2 Implementation Reference

WebView2 already provides a Window Controls Overlay feature that demonstrates the desired functionality:

• It renders native window controls on top of web content
• It exposes CSS environment variables for positioning content
• It provides a JavaScript API to interact with the overlay
• It maintains native button functionality

Use Cases

This feature would benefit various types of applications:

1. Modern productivity apps: Custom title bars that blend with the app's design language
2. Media players: Minimalist interfaces with integrated controls
3. Creative tools: Maximized workspace with subtle window controls
4. Web-based apps: Desktop versions of web apps with native-like interfaces
5. Cross-platform apps: Consistent title bar behavior across all platforms

Example Usage

<!DOCTYPE html>
<html>
<head>
    <style>
        /* Use CSS env variables to position content around window controls */
        body {
            margin: 0;
            padding-top: env(titlebar-area-height, 0px);
        }
        
        /* Custom title bar */
        .custom-titlebar {
            position: fixed;
            top: 0;
            left: 0;
            right: 0;
            height: env(titlebar-area-height, 32px);
            background-color: #2563eb;
            color: white;
            display: flex;
            align-items: center;
            padding-left: env(titlebar-area-x, 0px);
            /* Make the title bar draggable */
            -webkit-app-region: drag;
        }
        
        /* Content area */
        .content {
            padding: 20px;
        }
    </style>
</head>
<body>
    <div class="custom-titlebar">
        <h1>My App</h1>
    </div>
    <div class="content">
        <p>Content goes here...</p>
    </div>
    
    <script>
        // JavaScript API example
        if (window.windowControlsOverlay) {
            console.log('Window Controls Overlay supported');
            console.log('Overlay geometry:', window.windowControlsOverlay.getGeometry());
            
            // Listen for overlay changes
            window.windowControlsOverlay.addEventListener('geometrychange', (event) => {
                console.log('Overlay geometry changed:', event.geometry);
            });
        }
    </script>
</body>
</html>

Benefits for Wry

Implementing the Window Controls Overlay API would:

1. Improve developer experience: Reduce the complexity of creating custom title bars
2. Enhance app appearance: Enable modern, native-looking interfaces
3. Increase platform consistency: Provide a consistent solution across all platforms
4. Attract more developers: Make Wry more appealing for building modern desktop apps
5. Align with modern web standards: Follow the direction of other web-based desktop frameworks

This feature would position Wry as a more competitive alternative to other desktop frameworks by providing modern UI capabilities while maintaining its lightweight nature.

References

• WebView2 Window Controls Overlay Documentation
• Electron Window Controls Overlay
• CSS Environment Variables for Window Controls

[FabianLars]

This is not yet supported by WebView2. WCO is still only in prerelease versions which we sadly cannot use in Tauri/Wry. It has been like that for quite some time, at this point i wonder whether we'll see it being stabilized in 2026... ref MicrosoftEdge/WebView2Feedback#4532

p.s. i know you mean well but these AI issues aren't exactly good and wayyyy to much text.