Fix alt key mappings for mac (#12231)

docs/cli/keyboard-shortcuts.md

@@ -67,3 +67,12 @@ This document lists the available keyboard shortcuts in the Gemini CLI.
 | Shortcut | Description                       |
 | -------- | --------------------------------- |
 | `Ctrl+G` | See context CLI received from IDE |
+
+## Meta+key combos on mac
+
+On Mac, all Meta+char combos should work normally except for these three which
+are mapped to special functionality.
+
+- `meta+b`: "∫" back one word
+- `meta+f`: "ƒ" forward one word
+- `meta+m`: "µ" toggle markup view

packages/cli/src/ui/contexts/KeypressContext.test.tsx

@@ -872,14 +872,32 @@ describe('Kitty Sequence Parsing', () => {
     vi.useRealTimers();
   });
 
+  describe('Cross-terminal Alt key handling (simulating macOS)', () => {
+    let originalPlatform: NodeJS.Platform;
+
+    beforeEach(() => {
+      originalPlatform = process.platform;
+      Object.defineProperty(process, 'platform', {
+        value: 'darwin',
+        configurable: true,
+      });
+    });
+
+    afterEach(() => {
+      Object.defineProperty(process, 'platform', {
+        value: originalPlatform,
+        configurable: true,
+      });
+    });
+
     // Terminals to test
     const terminals = ['iTerm2', 'Ghostty', 'MacTerminal', 'VSCodeTerminal'];
 
     // Key mappings: letter -> [keycode, accented character]
     const keys: Record<string, [number, string]> = {
-    a: [97, 'å'],
+      b: [98, '\u222B'],
-    o: [111, 'ø'],
+      f: [102, '\u0192'],
-    m: [109, 'µ'],
+      m: [109, '\u00B5'],
     };
 
     it.each(
@@ -965,6 +983,7 @@ describe('Kitty Sequence Parsing', () => {
         );
       },
     );
+  });
 
   describe('Backslash key handling', () => {
     beforeEach(() => {

packages/cli/src/ui/contexts/KeypressContext.tsx

@@ -48,33 +48,12 @@ export const PASTE_CODE_TIMEOUT_MS = 50; // Flush incomplete paste code after 50
 export const SINGLE_QUOTE = "'";
 export const DOUBLE_QUOTE = '"';
 
-const ALT_KEY_CHARACTER_MAP: Record<string, string> = {
+// On Mac, hitting alt+char will yield funny characters.
-  '\u00E5': 'a',
+// Remap these three since we listen for them.
-  '\u222B': 'b',
+const MAC_ALT_KEY_CHARACTER_MAP: Record<string, string> = {
-  '\u00E7': 'c',
+  '\u222B': 'b', // "∫" back one word
-  '\u2202': 'd',
+  '\u0192': 'f', // "ƒ" forward one word
-  '\u00B4': 'e',
+  '\u00B5': 'm', // "µ" toggle markup view
-  '\u0192': 'f',
-  '\u00A9': 'g',
-  '\u02D9': 'h',
-  '\u02C6': 'i',
-  '\u2206': 'j',
-  '\u02DA': 'k',
-  '\u00AC': 'l',
-  '\u00B5': 'm',
-  '\u02DC': 'n',
-  '\u00F8': 'o',
-  '\u03C0': 'p',
-  '\u0153': 'q',
-  '\u00AE': 'r',
-  '\u00DF': 's',
-  '\u2020': 't',
-  '\u00A8': 'u',
-  '\u221A': 'v',
-  '\u2211': 'w',
-  '\u2248': 'x',
-  '\u00A5': 'y',
-  '\u03A9': 'z',
 };
 
 /**
@@ -615,8 +594,8 @@ export function KeypressProvider({
         return;
       }
 
-      const mappedLetter = ALT_KEY_CHARACTER_MAP[key.sequence];
+      const mappedLetter = MAC_ALT_KEY_CHARACTER_MAP[key.sequence];
-      if (mappedLetter && !key.meta) {
+      if (process.platform === 'darwin' && mappedLetter && !key.meta) {
         broadcast({
           name: mappedLetter,
           ctrl: false,