Description

A Wails v2 frameless Windows window with a custom frontend titlebar does not behave like a native Windows titlebar when dragged down from maximized state.

In restored/normal state, dragging the custom titlebar via the Wails/CSS app-region drag behavior can move the window. However, when maximized, dragging downward from the custom titlebar does not reliably restore the window and continue moving it under the cursor.

A similar class of issue appears in multi-monitor scenarios, where moving the frameless window between monitors does not preserve normal native Windows shell behavior.

The maximized titlebar drag-down issue was also reproduced in a single-monitor setup after disconnecting the secondary monitor, so it does not appear to be limited to multi-monitor setups.

To Reproduce

1. Create a minimal Wails v2 Windows app.
2. Configure the app window as frameless.
3. Add a custom frontend titlebar at the top of the window.
4. Mark the titlebar drag area with Wails/CSS app-region drag behavior.
5. Run the app on Windows.
6. In restored/normal state, drag the custom titlebar and confirm the window moves.
7. Maximize the window.
8. Drag downward from the custom titlebar, the same way a user would drag a native maximized Windows titlebar.
9. Repeat the flow with multiple monitors, including moving the window between monitors.
10. Disconnect the secondary monitor and repeat the maximized titlebar drag-down flow on a single-monitor setup.

Expected behaviour

Dragging downward from the custom titlebar while maximized should match native Windows titlebar behavior:

• The window restores from maximized state.
• The restored window remains attached to the cursor.
• The user can continue moving the window naturally.
• Multi-monitor movement preserves normal Windows shell behavior.
• Snap, restore, resize, and monitor work-area behavior remain consistent with native Windows windows.

Screenshots

No screenshots attached. The issue is primarily visible through interactive window drag/shell behavior.

Attempted Fixes

I tried several Wails-only approaches, but none produced acceptable native Windows shell behavior:

• Using the CSS/app-region drag path for the custom titlebar.
• Disabling the drag region while maximized.
• Calling Wails runtime window APIs such as unmaximise and set-position as a fallback.
• Trying WindowStartDrag / HTCAPTION-like native drag initiation.
• Triggering runtime resize/redraw/resync-style fallbacks after restore/move.

These approaches either did not fix maximized drag-down restore/move behavior, did not behave like native Windows shell motion, or regressed normal restored titlebar movement.

System Details

# Wails

Version | v2.12.0

# System

OS           | Windows 10 Home Single Language
Version      | 2009 (Build: 26200)
ID           | 25H2
Branding     | Windows 11 Home Single Language
Go Version   | go1.26.3
Platform     | windows
Architecture | amd64
CPU          | 12th Gen Intel(R) Core(TM) i7-12650H
GPU 1        | Intel(R) UHD Graphics (Intel Corporation) - Driver: 32.0.101.7082
GPU 2        | NVIDIA GeForce RTX 4060 Laptop GPU (NVIDIA) - Driver: 32.0.15.9597
Memory       | 32GB

# Dependencies

Dependency | Status    | Version
WebView2   | Installed | 148.0.3967.96
Nodejs     | Installed | 26.1.0
npm        | Installed | 11.13.0
upx        | Available | Optional dependency
nsis       | Available | Optional dependency

# Diagnosis

SUCCESS Your system is ready for Wails development.

Additional context

Questions:

1. Is native Windows maximized titlebar drag-down restore+move expected to work for Wails frameless windows with custom titlebars?
2. Is there a supported Wails API or recommended pattern for initiating native titlebar drag behavior while preserving Windows shell semantics?
3. Should Wails app-region drag regions map to native HTCAPTION behavior for maximized frameless windows, or is this currently unsupported?
4. Are there known limitations with Wails frameless windows, WebView2 bounds, and multi-monitor shell movement?
5. Is there a recommended minimal implementation pattern for custom titlebars that need native Windows drag, restore, Snap, and multi-monitor behavior?
6. Would this be considered a Wails runtime/window bug, a missing API, or an unsupported limitation of frameless custom titlebars on Windows?