Skip to content

fix(input): keep macOS menu shortcuts and Cmd-dropping encodings out of terminals - #424

Merged
forketyfork merged 2 commits into
mainfrom
fix/system-shortcut-key-leaks
Nov 6, 2026
Merged

forketyfork merged 2 commits into
mainfrom
fix/system-shortcut-key-leaks

Conversation

@forketyfork

Copy link
Copy Markdown
Owner

TLDR

On macOS, Ctrl+Cmd+F makes the window full screen. In Architect, this key press also went to the terminal and wrote the text ^[[102;5u (the code for Ctrl+F) into it. Now Architect does not send macOS menu shortcuts to the terminal. Also, when the terminal's key format cannot show the Cmd key, Architect sends nothing. It does not send a different key.

Issue

SDL sends every key press to the application before AppKit runs the matching menu item. SDL installs these menu shortcuts: Hide ⌘H, Hide Others ⌥⌘H, Quit ⌘Q, Close ⌘W, Minimize ⌘M, and Toggle Full Screen ⌃⌘F. No Architect shortcut matched Ctrl+Cmd+F, so the press went to the ghostty-vt key encoder (introduced in #412):

  • Legacy encoding (no Kitty flags, for example a plain shell): Ctrl blocks the C0 path, and Cmd blocks the plain ^F path. The press therefore reaches Ghostty's fixterms CSI u branch, whose modifier set has no Cmd bit. The result is \x1b[102;5u, which is exactly Ctrl+F. Before fix(input): preserve terminal key modifiers and event actions #412, the same press sent ^F, which shells consume silently, so the leak was not visible.
  • Kitty encoding: the press arrives as \x1b[102;13u, although macOS already used it to toggle full screen.

A sweep over all mapped keys with every Command combination found more legacy-mode cases where Cmd is silently dropped:

Keys Legacy output before Read by the app as
Ctrl+Cmd(+Shift)+any text key (F, D, Space, digits, punctuation…) \x1b[<cp>;5u / ;6u Ctrl(+Shift)+key
Cmd+Shift / Cmd+Opt / Ctrl+Cmd + Backspace \x7f / \x1b\x7f / \x08 Backspace / Opt+Backspace / Ctrl+Backspace
Cmd(+any)+keypad Enter (also with modifyOtherKeys 2) \r Enter

Solution

  • input.isMacosMenuKeyEquivalent matches the exact key and modifier sets of SDL's application menu. On macOS, TerminalKeyPresses.handlePress drops these presses, so their repeats and releases never reach a terminal either.
  • encodeKeyEvent sends nothing for Command-modified keys whose encoding has no Cmd bit: text keys and Backspace in legacy mode without modifyOtherKeys 2, and keypad Enter outside Kitty. Encodings that do carry Cmd (Kitty, modifyOtherKeys 2, xterm-style navigation/function/Enter/Tab/Escape parameters) are unchanged. So are the explicit ⌘←/⌘→/⌘⌫ line-editing bindings.
  • A property test checks every mapped key × every Command combination × legacy / application-cursor / modifyOtherKeys 2 / Kitty / Kitty with event reporting × press/repeat/release. The output must be empty, an explicit line-editing binding, or a CSI sequence whose modifier parameter has the Cmd bit. Both new tests failed before the fix.

Context

  • Regression surfaced by fix(input): preserve terminal key modifiers and event actions #412, which moved key encoding to ghostty-vt.
  • Not changed, but found during the sweep and still open:
    • SDL does not report Fn/Globe as a modifier. If AppKit handles Globe+F (full screen) or Globe+Ctrl+arrows (window tiling) as menu shortcuts, the presses arrive in Architect as plain or Ctrl-only keys, and Architect cannot tell them apart. I could not verify this without a physical keyboard.
    • SDL resets its key state when the window loses focus and only learns about modifiers again from the next flags-changed event. If the full-screen transition briefly removes key focus while the keys are still held, a later auto-repeat could arrive with stale modifiers. This is inferred from SDL's Cocoa sources, not observed.
    • Key-ups whose press the system consumed (⌘Tab, Mission Control, screenshots) are dropped by SDL, because it never recorded the press, and by Architect, which sends releases only for presses it delivered. No change needed.

Test plan

  • In a plain shell in Architect, press ⌃⌘F twice (enter and exit full screen): nothing is typed at the prompt.
  • In a Kitty-aware app (for example Claude Code or Codex), press ⌃⌘F: the app gets no key, and the window toggles full screen.
  • Press Globe+F and, on macOS 15+, Globe+Ctrl+arrow tiling shortcuts in a plain shell. Report any typed characters: this path is not covered by this PR.

…of terminals

Issue: Pressing Ctrl+Cmd+F to toggle full screen wrote ^[[102;5u (Ctrl+F with
Cmd dropped) into the focused terminal; the same class of leak affected other
Command chords that macOS consumes or that the terminal encoding cannot carry.

Solution: SDL queues every key press before AppKit performs the matching item
of the application menu SDL installs, so Architect forwarded Ctrl+Cmd+F to the
ghostty-vt encoder. In legacy mode Ghostty's fixterms CSI u has no Cmd bit and
emits Ctrl+F; with Kitty the full-screen press still reached the application.
Exact SDL menu key equivalents are now never delivered to a terminal, and
legacy encodings send nothing for Command-modified text keys, Backspace, and
keypad Enter instead of a different key. A property test checks every mapped
key and Command combination across legacy, modifyOtherKeys, and Kitty modes.
@forketyfork
forketyfork requested a balanced review from Copilot November 6, 2026 09:33
@forketyfork
forketyfork marked this pull request as ready for review November 6, 2026 09:33

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Key repeats bypass the menu-shortcut filter when Command is pressed while Ctrl+F is held, allowing Ctrl+Cmd+F to reach the terminal and requiring repeat filtering that preserves the original key release plus a regression test.

1 open issue
What changed in this PR

This PR follows up on #412’s keyboard encoder migration by preventing macOS menu shortcuts and Command-dropping encodings from reaching terminal applications.

Changes:

  • Filters exact macOS menu shortcuts before recording terminal presses.
  • Suppresses Command chords when the active encoding cannot preserve Command, while retaining explicit line-editing bindings.
  • Adds regression coverage and updates user and developer documentation.

Builds and tests were not run during this review.

File Description
src/​input/​mapper.zig Adds menu-chord matching, encoding guards, and regression tests.
src/​c.zig Exports SDL constants used by matching and tests.
src/​app/​input_keys.zig Filters macOS menu presses and tests terminal delivery.
README.md Documents shortcut filtering and unsupported Command chords.
docs/​development.md Describes Command-preservation regression coverage.
docs/​ARCHITECTURE.md Explains menu filtering and encoding safeguards.

Review effort: Balanced

Comment thread src/app/input_keys.zig Resolved
…hortcut

Issue: Review of #424 noted that pressing Command while Ctrl+F is held makes
the delivered press's repeats Ctrl+Cmd+F, which the repeat path forwarded to
Kitty and modifyOtherKeys terminals despite being the full-screen shortcut.

Solution: Repeats of a delivered press now pass the same macOS menu key
equivalent check as presses. Filtered repeats are not forwarded, but the press
stays owned, so its release still reaches the original terminal.
@forketyfork
forketyfork merged commit e06f212 into main Nov 6, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants