macOS terminal UX: verification handoff

[ohernandezdev]

Summary

The code fix for the macOS terminal Option-key / oh-my-zsh issues is already merged to main (commits 7d7a556, 59fe401 — v0.8.17). This PR only adds a handoff doc (docs/handoff-macos-terminal-verification.md) for whoever finishes verifying it on a real Mac — everything so far was authored from a Windows machine with no macOS hardware access.

Handoff for the next Claude Code session (macOS)

Already done, merged to main:

• src/main.ts: plain Option+Left / Option+Right now hand-emit \x1bb / \x1bf to the PTY (readline's default backward-word/forward-word bindings), scoped to just those two keys.
• Do not set xterm.js macOptionIsMeta: true. That was tried and reverted — it turns every Option-modified key into an ESC-prefixed byte, breaking the Option-key dead-key accent composition (ñ, á, ü) that src/xtermDeadKeyAddon.ts exists to support. Any further fix must stay scoped, not blanket-flip Option-as-Meta.
• Global shortcuts (alt+x/g/a/p/n, ctrl+alt+p in src-tauri/src/lib.rs) audited — no overlap with arrow/Option+Shift chords, nothing changed there.
• Added a Rust test (zsh_zdotdir_bootstrap_sources_user_zshrc) that runs the real ZDOTDIR bootstrap through an actual zsh binary — passes on the macos-latest GitHub Actions runner, proving the sourcing logic works. It's a synthetic .zshrc in an isolated process, not a real oh-my-zsh install inside the running app.

Needs a real macOS run (npm run tauri dev or the CI-built app):

1. Type hola mundo, press Option+Left twice — cursor should land between the two words.
2. Press Option+N (or your layout's accent dead-key) — should still compose ñ, not send a raw Meta byte. This is the regression the scoped fix is meant to avoid — check it explicitly.
3. Whatever combo Claude Code CLI uses for its own word navigation (assumed Option+Shift+Arrow) should reach the shell/CLI unmodified, not get swallowed by afkode's global shortcuts.
4. A fresh terminal tab should show the real oh-my-zsh prompt/theme, not the bare default.
5. Regression-check existing Cmd+C copy / Cmd+Up/Down block nav shortcuts still work.

Full detail in docs/handoff-macos-terminal-verification.md.

Test plan

• Run on macOS, verify all 5 items above
• Fix and iterate if any fail — the Option+Arrow handler is narrowly scoped (isMac() + exact ev.code check) so it should be safe to adjust

[ohernandezdev]

Verified all 5 checks on real macOS 15.7.7 hardware (see updated docs/handoff-macos-terminal-verification.md for full detail):

• ✅ Option+Left/Right word-jump
• ❌→✅ Option+N dead-key (ñ/ã/õ) — found a real regression: alt+n was registered as an OS-level global shortcut (DND toggle), which swallowed the keystroke before the webview/dead-key addon ever saw it, breaking accent composition system-wide. Fixed on main in 50a653c by moving it to alt+shift+n.
• ✅ Option+Shift+Arrow reaches the shell/CLI untouched
• ✅ Real oh-my-zsh prompt/theme loads in a fresh tab
• ✅ Cmd+C copy / Cmd+Up-Down block nav regression-checked, no issues
• ✅ cargo test 10/10 on real hardware, including zsh_zdotdir_bootstrap_sources_user_zshrc

Shipped as v0.8.18 (tag pushed, release workflow running).