fix(darwin): add DisableEscapeExitsFullscreen opt-in to mac.Options

[leaanthony]

fix(darwin): add DisableEscapeExitsFullscreen opt-in to mac.Options

PR #5242 overrides cancelOperation: in WailsWindow unconditionally,
which means Escape can never exit fullscreen for any Wails v2 app — even
ones that don't need that behaviour. This PR refactors the override to
be opt-in via a new Mac-only option.

What changed

v2/pkg/options/mac/mac.go

// DisableEscapeExitsFullscreen prevents the Escape key from exiting
// fullscreen mode.  When true, web content can handle the Escape key
// (e.g. to close modals) without triggering the macOS system behaviour
// that exits the fullscreen window.
DisableEscapeExitsFullscreen bool

v2/internal/frontend/desktop/darwin/WailsContext.m — cancelOperation: is guarded:

- (void)cancelOperation:(id)sender {
    if (self.disableEscapeExitsFullscreen &&
        (self.styleMask & NSWindowStyleMaskFullScreen) == NSWindowStyleMaskFullScreen) {
        return;
    }
    [super cancelOperation:sender];
}

The flag is threaded through the C bridge:
window.go → Application.h/.m (Create() signature) → WailsContext.h/.m (CreateWindow: signature + WailsWindow property).

Behaviour

Option	Escape in fullscreen
DisableEscapeExitsFullscreen: false (default)	exits fullscreen (unchanged macOS behaviour)
DisableEscapeExitsFullscreen: true	swallowed; JS keydown handlers still fire

Usage

&options.App{
    Mac: &mac.Options{
        DisableEscapeExitsFullscreen: true,
    },
}

Files

• v2/pkg/options/mac/mac.go — new option field
• v2/internal/frontend/desktop/darwin/window.go — read + pass to C
• v2/internal/frontend/desktop/darwin/Application.h/.m — updated Create() signature
• v2/internal/frontend/desktop/darwin/WailsContext.h/.m — WailsWindow property, conditional guard, updated CreateWindow: signature
• v2/test/4649/test_esc_fullscreen.go — updated test docs

Closes #4649
Supersedes #5242

Summary by CodeRabbit

• New Features

  • Added a macOS option to disable Escape exiting fullscreen, so web content can handle the Escape key while fullscreen is preserved; configurable per window.

• Tests

  • Added a macOS-only manual test program with guidance to verify Escape-key behavior in fullscreen scenarios (option enabled vs default).

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4813518f-b06d-4f29-b273-0ccc90ce6289

📥 Commits

Reviewing files that changed from the base of the PR and between 3f3a057 and 39deddc.

📒 Files selected for processing (1)

• v2/test/4649/test_esc_fullscreen.go

---

Walkthrough

Adds a macOS option and threads a new flag through Go and Objective‑C code to prevent the Escape key from exiting fullscreen, and implements an Objective‑C override to respect that flag per window.

Changes

Escape Fullscreen Control

Layer / File(s)	Summary
Configuration Definition v2/pkg/options/mac/mac.go	Adds DisableEscapeExitsFullscreen bool to mac Options.
Go -> C Binding v2/internal/frontend/desktop/darwin/window.go	Reads frontendOptions.Mac.DisableEscapeExitsFullscreen, sets disableEscapeExitsFullscreen C-int, and passes it to C.Create(...).
C Exported Entry v2/internal/frontend/desktop/darwin/Application.h, v2/internal/frontend/desktop/darwin/Application.m	Extends exported Create signature with disableEscapeExitsFullscreen and forwards it into CreateWindow:.
Objective‑C Interface v2/internal/frontend/desktop/darwin/WailsContext.h	Adds WailsWindow property disableEscapeExitsFullscreen and extends CreateWindow: declaration to accept the new boolean parameter.
Objective‑C Implementation v2/internal/frontend/desktop/darwin/WailsContext.m	Adds WailsWindow override - (void)cancelOperation:(id)sender that returns early when disableEscapeExitsFullscreen is true and the window is fullscreen; extends CreateWindow: implementation and assigns the flag to mainWindow.
Manual Test / Docs v2/test/4649/test_esc_fullscreen.go	Adds macOS-only manual test program documenting verification steps for both flag enabled and default behavior.

Sequence Diagram(s)

sequenceDiagram
  participant Go as Go (window.go)
  participant C as C bridge (Application)
  participant ObjC as ObjC (WailsContext / WailsWindow)
  participant macOS as macOS window system

  Go->>C: Call C.Create(..., disableEscapeExitsFullscreen)
  C->>ObjC: CreateWindow(..., disableEscapeExitsFullscreen)
  ObjC->>ObjC: Assign flag to mainWindow.disableEscapeExitsFullscreen
  Note over ObjC,macOS: User presses Esc while fullscreen
  macOS->>ObjC: cancelOperation: triggered
  ObjC-->>macOS: if flag true && fullscreen -> ignore Esc (no exit)
  ObjC-->>macOS: else -> call super (default behavior)

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(darwin): add DisableEscapeExitsFullscreen opt-in to mac.Options #5310 — Similar changes adding DisableEscapeExitsFullscreen and threading it through macOS Application/WailsContext/window.go.

Suggested labels

reviewed ✅

Poem

"I'm a rabbit in the macOS glen,
I guard the fullscreen den;
Press Esc if you must,
the modal stays and you trust—
hop on, the key's yours again! 🐇"

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is comprehensive, explaining the problem from PR #5242, the solution, behavior matrix, usage example, and all files changed. However, the required template sections like 'Type of change', 'How Has This Been Tested', and 'Checklist' are not filled out.	Complete the template by selecting the type of change (Bug fix), specifying test configuration, and checking relevant checklist items such as changelog update and test verification.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a new DisableEscapeExitsFullscreen opt-in option to mac.Options for controlling Escape key behavior in fullscreen mode on macOS.
Linked Issues check	✅ Passed	The PR fully addresses issue #4649 by providing the requested functionality: a way to prevent Escape from exiting fullscreen while allowing web handlers to manage the Escape key, implemented through the new DisableEscapeExitsFullscreen option in mac.Options.
Out of Scope Changes check	✅ Passed	All code changes are directly scoped to implementing the DisableEscapeExitsFullscreen option and threading it through the C bridge, with one test file documenting expected behavior. No extraneous changes detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/engineer-mac/eaf56c93

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.11.4)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 6/8 reviews remaining, refill in 13 minutes and 36 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds a macOS-only, opt-in switch in Wails v2 to prevent Escape from exiting fullscreen by conditionally swallowing cancelOperation: only when configured, restoring default macOS behavior for apps that don’t need the override.

Changes:

• Added DisableEscapeExitsFullscreen to v2/pkg/options/mac.Options.
• Threaded the new flag through the Go → C bridge (Create/CreateWindow) and applied it to WailsWindow to guard the cancelOperation: override.
• Updated the existing manual test documentation for issue #4649.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
v2/pkg/options/mac/mac.go	Introduces DisableEscapeExitsFullscreen option on macOS options.
v2/internal/frontend/desktop/darwin/window.go	Reads the option and passes it into the C Create call.
v2/internal/frontend/desktop/darwin/Application.h	Extends Create(...) signature to accept the new flag.
v2/internal/frontend/desktop/darwin/Application.m	Passes the new flag through to WailsContext CreateWindow.
v2/internal/frontend/desktop/darwin/WailsContext.h	Adds WailsWindow.disableEscapeExitsFullscreen and extends CreateWindow signature.
v2/internal/frontend/desktop/darwin/WailsContext.m	Guards cancelOperation: behavior based on the new flag and fullscreen state; assigns the flag to the window.
v2/test/4649/test_esc_fullscreen.go	Manual test guidance updates for the new opt-in behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.