macOS: BrowserBack/BrowserForward post a fixed US-ANSI ⌘[ and fire the wrong shortcut on non-US layouts

[jcbrizu]

Environment

• OpenLogi v0.8.5 (build 20260916), macOS
• Logitech MX Master 3S, Bluetooth-direct
• Keyboard layout: Latin American (com.apple.keylayout.LatinAmerican)
• schema_version = 7

Summary

Action::BrowserBack / BrowserForward are dispatched on macOS as a hardcoded Cmd+[ / Cmd+],
posted via CGEvent with a fixed US-ANSI virtual keycode. The active keyboard layout is never
consulted, so on a non-US layout the buttons fire whatever shortcut lives at that physical key
position.

On a Latin American layout the result is not a no-op — it is an actively wrong shortcut:

Button	Intended	Posts	LatAm layout yields	Observed in Finder
Forward	Cmd+]	Cmd + vk 0x1E (30)	Cmd + +	Zooms icon size
Back	Cmd+[	Cmd + vk 0x21 (33)	Cmd + dead-key accent	No-op; window loses focus

Cmd + is Finder's "increase icon size" shortcut, matching the reported symptom exactly.

Root cause

crates/openlogi-inject/src/inject/macos.rs:101-106

Shortcut::BrowserBack => "Cmd+[",
Shortcut::BrowserForward => "Cmd+]",

macos.rs:408-409 maps HID usage 0x2f ([) → vk 0x21, 0x30 (]) → vk 0x1E; macos.rs:289-298
posts that verbatim. CGEvent::new_keyboard_event takes a virtual keycode, i.e. a physical key
position — it is not remapped to the user's layout. Contrast Effect::Text → post_unicode, which
the code itself annotates as "layout-independent".

The important part: translating the character is NOT sufficient

The obvious fix — "resolve [ against the active layout and post that keycode" — is still wrong,
because macOS itself does not use [ on these layouts. Finder's Go menu on Latin American advertises:

Atrás      ⌘{
Adelante   ⌘}

Not ⌘[ / ⌘]. AppKit remaps the menu equivalent because [ is not conveniently typeable there.
Verified against the live layout with UCKeyTranslate:

vk 39 unshifted -> {      vk 39 + Shift -> [
vk 42 unshifted -> }      vk 42 + Shift -> ]
vk 33           -> dead key (accent)
vk 30           -> +

So an implementation that faithfully produces the character [ would post Cmd+Shift+vk39 and
still fail, because the menu item is bound to {. I confirmed this empirically on the affected
machine: Cmd+Shift+' (→ ⌘[) did nothing in Finder, while Cmd+' (→ ⌘{) navigates correctly.

Conclusion: the chord an app actually listens for is app- and layout-dependent, and cannot be
derived from a hardcoded character. The robust route is the AX/menu path (ax_navigate_browser
already does this for Safari) generalised beyond Safari, or querying the target app's menu key
equivalent, rather than synthesising any fixed chord.

Why this is easy to miss: Safari masks it

crates/openlogi-agent-core/src/runtime.rs:130-151 routes navigation through ax_navigate_browser
(an AXPress on Safari's toolbar button) when Safari is frontmost, and runtime.rs:466-469
suppresses the keyboard fallback for that path. That route never touches the keyboard, so it is
immune to the layout bug.

A user on a non-US layout who tests in Safari sees Back/Forward work perfectly and only discovers the
breakage in Finder or Chrome. Both paths are visible in the agent log:

INFO openlogi_agent_core::runtime: browser nav debounced — duplicate dispatch path suppressed action=Browser Back

Secondary bug: RunAppleScript fails silently

While testing a workaround, Action::RunAppleScript with a System Events keystroke was dispatched
correctly (confirmed via gesture::dispatch: HID++ button → binding ... action=Run AppleScript) but
produced nothing. Cause: macOS attributes Accessibility to the spawned /usr/bin/osascript binary,
which holds no grant of its own and, launched headless, triggers no prompt.

run_apple_script at macos.rs:527 discards the result:

let _ = std::process::Command::new("osascript").args(["-e", src]).output();

so nothing is logged. Suggest logging non-zero exit / stderr — a silent no-op here is very hard to
diagnose.

Relation to existing issues

• fix(core): stop seeding Back/Forward with a divertable default #1225 (merged, v0.8.4) correctly fixed HID++ diversion; the button is diverted and the action
  does fire. That fix works — it just exposed this independent bug. Note the symptom moved buttons:
  in Logitech MX Master 3S side buttons don't work for browser navigation #23 the Back button zoomed; after fix(core): stop seeding Back/Forward with a divertable default #1225 the Forward button zooms, because the reseeded
  defaults changed which button carries which chord.
• macOS: ax_navigate_browser has no callers — and AXPress is the layout-proof BrowserBack #1352 raises the fixed-⌘[ problem but frames it around ax_navigate_browser having no callers,
  which is stale as of v0.8.4 (it has a caller at runtime.rs:138). The layout half is still live on
  master, and the ⌘{ finding above shows the problem is deeper than the issue states.
• [Bug]: macOS: Back/Forward never navigate in Finder on a Bluetooth-direct MX Master 3S — MouseBack posts a button 4/5 Finder ignores, and the default ⌘[ binding is never HID++-diverted so it dies in the fail-closed hook #1263 / Logitech MX Master 3S side buttons don't work for browser navigation #23 / [Bug]: Back and Forward Buttons not working #354 / [Bug]: Back and Forward buttons on MX Anywhere 3 not working in Safari. #736 / [Bug]: Back and forward button binded to side buttons on MX Master 3 does not work on Safari, macOS 26.6.2 #1118 — same user-visible symptom.

Workaround for affected users

Per-app profile with a chord chosen so the physical key lands on the character the app's menu
actually uses. On Latin American:

[devices."serial:XXXX".bindings]
Back = "MouseBack"
Forward = "MouseForward"

[devices."serial:XXXX".per_app_bindings."com.apple.Safari"]
Back = "BrowserBack"          # AX route, layout-proof
Forward = "BrowserForward"

[devices."serial:XXXX".per_app_bindings."com.apple.finder"]
Back = { CustomShortcut = "Cmd+'" }    # ' -> HID 0x34 -> vk 39 -> '{' on LatAm -> ⌘{
Forward = { CustomShortcut = "Cmd+\\" } # \ -> HID 0x31 -> vk 42 -> '}' on LatAm -> ⌘}

This is layout-specific and only works because the user can hand-pick a US character whose keycode
happens to land on the right glyph — not a general solution.