fix(v2): Prevent Esc from exiting fullscreen on macOS

v2/internal/frontend/desktop/darwin/Application.h

@@ -17,7 +17,7 @@
 #define WindowStartsMinimised 2
 #define WindowStartsFullscreen 3
 
-WailsContext* Create(const char* title, int width, int height, int frameless, int resizable, int zoomable, int fullscreen, int fullSizeContent, int hideTitleBar, int titlebarAppearsTransparent, int hideTitle, int useToolbar, int hideToolbarSeparator, int webviewIsTransparent, int alwaysOnTop, int hideWindowOnClose, const char *appearance, int windowIsTranslucent, int contentProtection, int devtoolsEnabled, int defaultContextMenuEnabled, int windowStartState, int startsHidden, int minWidth, int minHeight, int maxWidth, int maxHeight, bool fraudulentWebsiteWarningEnabled, struct Preferences preferences, int singleInstanceLockEnabled, const char* singleInstanceUniqueId, bool enableDragAndDrop, bool disableWebViewDragAndDrop);
+WailsContext* Create(const char* title, int width, int height, int frameless, int resizable, int zoomable, int fullscreen, int fullSizeContent, int hideTitleBar, int titlebarAppearsTransparent, int hideTitle, int useToolbar, int hideToolbarSeparator, int webviewIsTransparent, int alwaysOnTop, int hideWindowOnClose, const char *appearance, int windowIsTranslucent, int contentProtection, int devtoolsEnabled, int defaultContextMenuEnabled, int windowStartState, int startsHidden, int minWidth, int minHeight, int maxWidth, int maxHeight, bool fraudulentWebsiteWarningEnabled, struct Preferences preferences, int singleInstanceLockEnabled, const char* singleInstanceUniqueId, bool enableDragAndDrop, bool disableWebViewDragAndDrop, bool disableEscapeExitsFullscreen);
 void Run(void*, const char* url);
 
 void SetTitle(void* ctx, const char *title);

v2/internal/frontend/desktop/darwin/Application.m

@@ -14,7 +14,7 @@
 #import "WailsMenu.h"
 #import "WailsMenuItem.h"
 
-WailsContext* Create(const char* title, int width, int height, int frameless, int resizable, int zoomable, int fullscreen, int fullSizeContent, int hideTitleBar, int titlebarAppearsTransparent, int hideTitle, int useToolbar, int hideToolbarSeparator, int webviewIsTransparent, int alwaysOnTop, int hideWindowOnClose, const char *appearance, int windowIsTranslucent, int contentProtection, int devtoolsEnabled, int defaultContextMenuEnabled, int windowStartState, int startsHidden, int minWidth, int minHeight, int maxWidth, int maxHeight, bool fraudulentWebsiteWarningEnabled, struct Preferences preferences, int singleInstanceLockEnabled, const char* singleInstanceUniqueId, bool enableDragAndDrop, bool disableWebViewDragAndDrop) {
+WailsContext* Create(const char* title, int width, int height, int frameless, int resizable, int zoomable, int fullscreen, int fullSizeContent, int hideTitleBar, int titlebarAppearsTransparent, int hideTitle, int useToolbar, int hideToolbarSeparator, int webviewIsTransparent, int alwaysOnTop, int hideWindowOnClose, const char *appearance, int windowIsTranslucent, int contentProtection, int devtoolsEnabled, int defaultContextMenuEnabled, int windowStartState, int startsHidden, int minWidth, int minHeight, int maxWidth, int maxHeight, bool fraudulentWebsiteWarningEnabled, struct Preferences preferences, int singleInstanceLockEnabled, const char* singleInstanceUniqueId, bool enableDragAndDrop, bool disableWebViewDragAndDrop, bool disableEscapeExitsFullscreen) {
 
     [NSApplication sharedApplication];
 
@@ -27,7 +27,7 @@
         fullscreen = 1;
     }
 
-    [result CreateWindow:width :height :frameless :resizable :zoomable :fullscreen :fullSizeContent :hideTitleBar :titlebarAppearsTransparent :hideTitle :useToolbar :hideToolbarSeparator :webviewIsTransparent :hideWindowOnClose :safeInit(appearance) :windowIsTranslucent :minWidth :minHeight :maxWidth :maxHeight :fraudulentWebsiteWarningEnabled :preferences :enableDragAndDrop :disableWebViewDragAndDrop];
+    [result CreateWindow:width :height :frameless :resizable :zoomable :fullscreen :fullSizeContent :hideTitleBar :titlebarAppearsTransparent :hideTitle :useToolbar :hideToolbarSeparator :webviewIsTransparent :hideWindowOnClose :safeInit(appearance) :windowIsTranslucent :minWidth :minHeight :maxWidth :maxHeight :fraudulentWebsiteWarningEnabled :preferences :enableDragAndDrop :disableWebViewDragAndDrop :disableEscapeExitsFullscreen];
     [result SetTitle:safeInit(title)];
     [result Center];
 

v2/internal/frontend/desktop/darwin/WailsContext.h

@@ -24,6 +24,7 @@
 
 @property NSSize userMinSize;
 @property NSSize userMaxSize;
+@property bool disableEscapeExitsFullscreen;
 
 - (BOOL) canBecomeKeyWindow;
 - (void) applyWindowConstraints;
@@ -65,7 +66,7 @@ struct Preferences {
   bool *fullscreenEnabled;
 };
 
-- (void) CreateWindow:(int)width :(int)height :(bool)frameless :(bool)resizable :(bool)zoomable :(bool)fullscreen :(bool)fullSizeContent :(bool)hideTitleBar :(bool)titlebarAppearsTransparent  :(bool)hideTitle :(bool)useToolbar :(bool)hideToolbarSeparator :(bool)webviewIsTransparent :(bool)hideWindowOnClose :(NSString *)appearance :(bool)windowIsTranslucent :(int)minWidth :(int)minHeight :(int)maxWidth :(int)maxHeight :(bool)fraudulentWebsiteWarningEnabled :(struct Preferences)preferences :(bool)enableDragAndDrop :(bool)disableWebViewDragAndDrop;
+- (void) CreateWindow:(int)width :(int)height :(bool)frameless :(bool)resizable :(bool)zoomable :(bool)fullscreen :(bool)fullSizeContent :(bool)hideTitleBar :(bool)titlebarAppearsTransparent  :(bool)hideTitle :(bool)useToolbar :(bool)hideToolbarSeparator :(bool)webviewIsTransparent :(bool)hideWindowOnClose :(NSString *)appearance :(bool)windowIsTranslucent :(int)minWidth :(int)minHeight :(int)maxWidth :(int)maxHeight :(bool)fraudulentWebsiteWarningEnabled :(struct Preferences)preferences :(bool)enableDragAndDrop :(bool)disableWebViewDragAndDrop :(bool)disableEscapeExitsFullscreen;
 - (void) SetSize:(int)width :(int)height;
 - (void) SetPosition:(int)x :(int) y;
 - (void) SetMinSize:(int)minWidth :(int)minHeight;

v2/internal/frontend/desktop/darwin/WailsContext.m

@@ -35,6 +35,14 @@ - (void) disableWindowConstraints {
     [self setMaxSize:NSMakeSize(FLT_MAX, FLT_MAX)];
 }
 
+- (void)cancelOperation:(id)sender {
+    if (self.disableEscapeExitsFullscreen &&
+        (self.styleMask & NSWindowStyleMaskFullScreen) == NSWindowStyleMaskFullScreen) {
+        return;
+    }
+    [super cancelOperation:sender];
+}
+
 @end
 
 // Notifications
@@ -145,7 +153,7 @@ - (BOOL) isFullscreen {
     return NO;
 }
 
-- (void) CreateWindow:(int)width :(int)height :(bool)frameless :(bool)resizable :(bool)zoomable :(bool)fullscreen :(bool)fullSizeContent :(bool)hideTitleBar :(bool)titlebarAppearsTransparent :(bool)hideTitle :(bool)useToolbar :(bool)hideToolbarSeparator :(bool)webviewIsTransparent :(bool)hideWindowOnClose :(NSString*)appearance :(bool)windowIsTranslucent :(int)minWidth :(int)minHeight :(int)maxWidth :(int)maxHeight :(bool)fraudulentWebsiteWarningEnabled :(struct Preferences)preferences :(bool)enableDragAndDrop :(bool)disableWebViewDragAndDrop  {
+- (void) CreateWindow:(int)width :(int)height :(bool)frameless :(bool)resizable :(bool)zoomable :(bool)fullscreen :(bool)fullSizeContent :(bool)hideTitleBar :(bool)titlebarAppearsTransparent :(bool)hideTitle :(bool)useToolbar :(bool)hideToolbarSeparator :(bool)webviewIsTransparent :(bool)hideWindowOnClose :(NSString*)appearance :(bool)windowIsTranslucent :(int)minWidth :(int)minHeight :(int)maxWidth :(int)maxHeight :(bool)fraudulentWebsiteWarningEnabled :(struct Preferences)preferences :(bool)enableDragAndDrop :(bool)disableWebViewDragAndDrop :(bool)disableEscapeExitsFullscreen  {
     NSWindowStyleMask styleMask = 0;
 
     if( !frameless ) {
@@ -167,6 +175,7 @@ - (void) CreateWindow:(int)width :(int)height :(bool)frameless :(bool)resizable
 
     self.mainWindow = [[WailsWindow alloc] initWithContentRect:NSMakeRect(0, 0, width, height)
                                                       styleMask:styleMask backing:NSBackingStoreBuffered defer:NO];
+    self.mainWindow.disableEscapeExitsFullscreen = disableEscapeExitsFullscreen;
     if (!frameless && useToolbar) {
         id toolbar = [[NSToolbar alloc] initWithIdentifier:@"wails.toolbar"];
         [toolbar autorelease];

v2/internal/frontend/desktop/darwin/window.go

@@ -87,6 +87,7 @@ func NewWindow(frontendOptions *options.App, debug bool, devtools bool) *Window
 
 	enableDragAndDrop := C.bool(frontendOptions.DragAndDrop != nil && frontendOptions.DragAndDrop.EnableFileDrop)
 	disableWebViewDragAndDrop := C.bool(frontendOptions.DragAndDrop != nil && frontendOptions.DragAndDrop.DisableWebViewDrop)
+	disableEscapeExitsFullscreen := C.bool(frontendOptions.Mac != nil && frontendOptions.Mac.DisableEscapeExitsFullscreen)
 
 	if frontendOptions.Mac != nil {
 		mac := frontendOptions.Mac
@@ -125,7 +126,7 @@ func NewWindow(frontendOptions *options.App, debug bool, devtools bool) *Window
 		hideTitleBar, titlebarAppearsTransparent, hideTitle, useToolbar, hideToolbarSeparator, webviewIsTransparent,
 		alwaysOnTop, hideWindowOnClose, appearance, windowIsTranslucent, contentProtection, devtoolsEnabled, defaultContextMenuEnabled,
 		windowStartState, startsHidden, minWidth, minHeight, maxWidth, maxHeight, enableFraudulentWebsiteWarnings,
-		preferences, singleInstanceEnabled, singleInstanceUniqueId, enableDragAndDrop, disableWebViewDragAndDrop,
+		preferences, singleInstanceEnabled, singleInstanceUniqueId, enableDragAndDrop, disableWebViewDragAndDrop, disableEscapeExitsFullscreen,
 	)
 
 	// Create menu

v2/pkg/options/mac/mac.go

@@ -23,6 +23,11 @@ type Options struct {
 	WindowIsTranslucent  bool
 	Preferences          *Preferences
 	DisableZoom          bool
+	// DisableEscapeExitsFullscreen, when true, prevents the Esc key from
+	// exiting fullscreen mode. The keypress is swallowed by the window so
+	// web content can handle it (e.g. closing modals). Default false
+	// preserves standard macOS fullscreen behaviour.
+	DisableEscapeExitsFullscreen bool
 	// ActivationPolicy     ActivationPolicy
 	About      *AboutInfo
 	OnFileOpen func(filePath string) `json:"-"`

v2/test/4649/test_esc_fullscreen.go

@@ -0,0 +1,44 @@
+//go:build darwin
+// +build darwin
+
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+// This is a manual test program for issue #4649.
+// Run on macOS: go run v2/test/4649/test_esc_fullscreen.go
+//
+// The fix is opt-in via mac.Options.DisableEscapeExitsFullscreen.
+// Default behaviour (flag = false) preserves standard macOS fullscreen:
+// Esc exits fullscreen.
+//
+// Expected behaviour with the flag enabled (DisableEscapeExitsFullscreen: true):
+// 1. Window opens in fullscreen mode
+// 2. Pressing Esc should NOT exit fullscreen — the keypress is swallowed
+//    so web content (modals, custom Esc handlers) can consume it
+// 3. Pressing Cmd+Ctrl+F should still toggle fullscreen (exit)
+// 4. When NOT in fullscreen, Esc should still work normally
+//
+// Implementation: WailsWindow.cancelOperation: checks the
+// disableEscapeExitsFullscreen property (set from
+// mac.Options.DisableEscapeExitsFullscreen at window creation) AND
+// the fullscreen styleMask before swallowing the keypress.
+
+func main() {
+	fmt.Println("Test for issue #4649: opt-in flag to keep fullscreen on Esc (macOS)")
+	fmt.Println("")
+	fmt.Println("Set mac.Options.DisableEscapeExitsFullscreen = true to opt in.")
+	fmt.Println("")
+	fmt.Println("Manual verification (opt-in):")
+	fmt.Println("1. Configure &options.App{ Mac: &mac.Options{ DisableEscapeExitsFullscreen: true } }")
+	fmt.Println("2. Open a fullscreen window with an HTML modal dialog")
+	fmt.Println("3. Press Esc - the modal should close but NOT exit fullscreen")
+	fmt.Println("")
+	fmt.Println("Manual verification (default, flag unset):")
+	fmt.Println("1. Same app but with the flag omitted/false")
+	fmt.Println("2. Press Esc - the window should exit fullscreen (standard macOS behaviour)")
+	os.Exit(0)
+}