feat(macos): open context menus on native secondary click

JA
6d ago
+265-9

Summary

With AGENT_DEVICE_MACOS_APP_BACKEND=native, click --button secondary was refused, so SwiftUI .contextMenu and AppKit context menus could not be opened. The helper now runs AXShowMenu on the nearest element up the hit chain that offers it.

The app blocks while it tracks the open menu, so AXShowMenu never replies. The helper stops waiting after 0.5 s and reports success only if a new menu window of the app appears within 1 s. Otherwise:

  • No menu appeared: COMMAND_FAILED, reason: context-menu-not-observed (window-list-unreadable if the window list could not be read).
  • No element at the point offers a menu: UNSUPPORTED_OPERATION, helperReason: no-context-menu.

The next snapshot lists the open menu's items; click picks one.

Middle click and double-click stay refused. Double-click needs item 13's pointer-event path. On macOS 27 it needs an unexported setter (see the evidence file).

10 files. ADR 0031 amended. Part of #3213 (item 5).

Validation

At e8688c3de:

  • pnpm check:affected --run --head e8688c3de passed (exactCommit: true).
  • swift test in apple/macos-helper: 21 passed.

Live run (at 62926eae7; later commits change docs, comments, a test, and the unreadable-window-list path) on macOS 27.0 (26A428), dev CLI, background SwiftUI fixture. No fixture lane exists yet (item 3).

  • On a .contextMenu row: click --button secondary returned mechanism: ax-show-menu. snapshot -i showed [menu] with Rename and Delete. click on Delete ran its action.
  • On a Button with a menu: the menu opened, and the button action did not run.
  • On a plain button: refused with no-context-menu.